@milaboratories/pl-middle-layer 1.38.1 → 1.39.0

package/dist/js_render/index.d.ts

@@ -3,6 +3,54 @@ import { BlockCodeWithInfo, ConfigRenderLambda } from '@platforma-sdk/model';
 import { ComputableRenderingOps, Computable } from '@milaboratories/computable';
 import { QuickJSWASMModule } from 'quickjs-emscripten';
 import { BlockContextAny } from '../middle_layer/block_ctx';
+/**
+ * Creates a Computable that executes a render function (`fh`) from a block's code in a QuickJS virtual machine.
+ * This function handles both synchronous and asynchronous execution patterns of the sandboxed JS code.
+ *
+ * The overall data flow is as follows:
+ * 1. A QuickJS VM is initialized.
+ * 2. A `JsExecutionContext` is created to bridge the host (TypeScript) and guest (QuickJS) environments. It injects a
+ *    context object (`cfgRenderCtx`) into the VM, providing helper methods for the sandboxed code to interact with the
+ *    platform (e.g., to request data).
+ * 3. The block's Javascript bundle is evaluated in the VM.
+ * 4. The specified render function (`fh.handle`) is executed.
+ *
+ * Two execution paths are possible depending on the behavior of the render function:
+ *
+ * ### Synchronous Path
+ * If the render function computes its result without requesting any external data requiring asynchronous calculations,
+ * it executes synchronously.
+ * - The `computablesToResolve` map in `JsExecutionContext` remains empty.
+ * - The function returns an object with an `ir` field holding the result (`{ ir: importedResult }`).
+ *   Since `postprocessValue` is not specified, `ir` is treated as the final resolved value of the Computable.
+ * - The QuickJS VM is disposed of immediately as it's no longer needed.
+ *
+ * ### Asynchronous Path (with `postprocessValue`)
+ * If the render function needs external data requiring asynchronous calculations (e.g., fetching a file), it calls
+ * one of the injected helper methods. These methods don't return data directly. Instead, they:
+ *  a. Create a new `Computable` for the data request (e.g., to fetch a blob).
+ *  b. Register this new `Computable` in the `computablesToResolve` map.
+ *  c. Return a handle (string) to the sandboxed code.
+ *
+ * In this case:
+ * - The initial execution of the render function returns a scaffold of the final result, which depends on the pending
+ *   computables.
+ * - The `computablesToResolve` map is passed as the `ir` (initial result) to `Computable.makeRaw`.
+ * - The `postprocessValue` function is provided to handle the results once the computables are resolved.
+ * - The QuickJS VM is kept alive (`keepVmAlive = true`) because its state is needed in `postprocessValue`.
+ * - Once the `computable` framework resolves all dependencies, it calls `postprocessValue` with the resolved data.
+ * - `postprocessValue` feeds the resolved data back into the VM, allowing the sandboxed code to compute the final
+ *   result.
+ * - The VM is eventually disposed of when the host Computable is destroyed.
+ *
+ * @param env The middle layer environment.
+ * @param ctx The block context.
+ * @param fh The config render lambda to execute.
+ * @param codeWithInfo The block's code and feature flags.
+ * @param configKey A key for the configuration, used for cache busting.
+ * @param ops Options for the computable.
+ * @returns A `Computable` that will resolve to the result of the lambda execution.
+ */
 export declare function computableFromRF(env: MiddleLayerEnvironment, ctx: BlockContextAny, fh: ConfigRenderLambda, codeWithInfo: BlockCodeWithInfo, configKey: string, ops?: Partial<ComputableRenderingOps>): Computable<unknown>;
 export declare function executeSingleLambda(quickJs: QuickJSWASMModule, fh: ConfigRenderLambda, codeWithInfo: BlockCodeWithInfo, ...args: unknown[]): unknown;
 //# sourceMappingURL=index.d.ts.map

package/dist/js_render/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/js_render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGjE,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,eAAe,EACpB,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,OAAO,CAAC,sBAAsB,CAAM,GACxC,UAAU,CAAC,OAAO,CAAC,CAiErB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CA4BT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/js_render/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAI5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAYjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,sBAAsB,EAC3B,GAAG,EAAE,eAAe,EACpB,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,GAAE,OAAO,CAAC,sBAAsB,CAAM,GACxC,UAAU,CAAC,OAAO,CAAC,CA4ErB;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,EAAE,EAAE,kBAAkB,EACtB,YAAY,EAAE,iBAAiB,EAC/B,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CA4BT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-middle-layer",
-  "version": "1.38.1",
+  "version": "1.39.0",
   "description": "Pl Middle Layer",
   "engines": {
     "node": ">=20.16.0"
@@ -32,22 +32,22 @@
     "yaml": "^2.7.0",
     "zod": "~3.23.8",
     "remeda": "^2.22.6",
-    "@milaboratories/computable": "^2.6.0",
     "@milaboratories/pl-http": "^1.1.4",
-    "@milaboratories/resolve-helper": "^1.1.0",
     "@platforma-sdk/block-tools": "^2.5.63",
-    "@milaboratories/pl-drivers": "^1.6.0",
-    "@milaboratories/pl-model-backend": "~1.1.2",
+    "@milaboratories/resolve-helper": "^1.1.0",
     "@milaboratories/pl-client": "^2.11.2",
-    "@milaboratories/pl-tree": "~1.7.0",
+    "@milaboratories/pl-drivers": "^1.6.0",
     "@platforma-sdk/model": "~1.39.0",
-    "@milaboratories/pl-model-middle-layer": "~1.7.45",
-    "@milaboratories/ts-helpers": "^1.4.1",
     "@milaboratories/pl-model-common": "~1.16.0",
+    "@milaboratories/computable": "^2.6.0",
+    "@milaboratories/pl-tree": "~1.7.0",
     "@platforma-sdk/workflow-tengo": "4.9.2",
+    "@milaboratories/pl-model-backend": "~1.1.2",
+    "@milaboratories/pl-model-middle-layer": "~1.7.45",
+    "@milaboratories/pl-errors": "^1.1.9",
     "@milaboratories/pl-config": "^1.6.1",
     "@milaboratories/pl-deployments": "^2.4.3",
-    "@milaboratories/pl-errors": "^1.1.9"
+    "@milaboratories/ts-helpers": "^1.4.1"
   },
   "devDependencies": {
     "semver": "^7.7.2",

package/src/js_render/index.ts

@@ -9,6 +9,63 @@ import { JsExecutionContext } from './context';
 import type { BlockContextAny } from '../middle_layer/block_ctx';
 import { getDebugFlags } from '../debug';
 
+function logOutputStatus(handle: string, renderedResult: unknown, stable: boolean, recalculationCounter: number, unstableMarker?: string) {
+  if (getDebugFlags().logOutputStatus && (getDebugFlags().logOutputStatus === 'any' || !stable)) {
+    if (stable)
+      console.log(`Stable output ${handle} calculated ${renderedResult !== undefined ? 'defined' : 'undefined'}; (#${recalculationCounter})`);
+    else
+      console.log(`Unstable output ${handle}; marker = ${unstableMarker}; ${renderedResult !== undefined ? 'defined' : 'undefined'} (#${recalculationCounter})`);
+  }
+}
+
+/**
+ * Creates a Computable that executes a render function (`fh`) from a block's code in a QuickJS virtual machine.
+ * This function handles both synchronous and asynchronous execution patterns of the sandboxed JS code.
+ *
+ * The overall data flow is as follows:
+ * 1. A QuickJS VM is initialized.
+ * 2. A `JsExecutionContext` is created to bridge the host (TypeScript) and guest (QuickJS) environments. It injects a
+ *    context object (`cfgRenderCtx`) into the VM, providing helper methods for the sandboxed code to interact with the
+ *    platform (e.g., to request data).
+ * 3. The block's Javascript bundle is evaluated in the VM.
+ * 4. The specified render function (`fh.handle`) is executed.
+ *
+ * Two execution paths are possible depending on the behavior of the render function:
+ *
+ * ### Synchronous Path
+ * If the render function computes its result without requesting any external data requiring asynchronous calculations,
+ * it executes synchronously.
+ * - The `computablesToResolve` map in `JsExecutionContext` remains empty.
+ * - The function returns an object with an `ir` field holding the result (`{ ir: importedResult }`).
+ *   Since `postprocessValue` is not specified, `ir` is treated as the final resolved value of the Computable.
+ * - The QuickJS VM is disposed of immediately as it's no longer needed.
+ *
+ * ### Asynchronous Path (with `postprocessValue`)
+ * If the render function needs external data requiring asynchronous calculations (e.g., fetching a file), it calls
+ * one of the injected helper methods. These methods don't return data directly. Instead, they:
+ *  a. Create a new `Computable` for the data request (e.g., to fetch a blob).
+ *  b. Register this new `Computable` in the `computablesToResolve` map.
+ *  c. Return a handle (string) to the sandboxed code.
+ *
+ * In this case:
+ * - The initial execution of the render function returns a scaffold of the final result, which depends on the pending
+ *   computables.
+ * - The `computablesToResolve` map is passed as the `ir` (initial result) to `Computable.makeRaw`.
+ * - The `postprocessValue` function is provided to handle the results once the computables are resolved.
+ * - The QuickJS VM is kept alive (`keepVmAlive = true`) because its state is needed in `postprocessValue`.
+ * - Once the `computable` framework resolves all dependencies, it calls `postprocessValue` with the resolved data.
+ * - `postprocessValue` feeds the resolved data back into the VM, allowing the sandboxed code to compute the final
+ *   result.
+ * - The VM is eventually disposed of when the host Computable is destroyed.
+ *
+ * @param env The middle layer environment.
+ * @param ctx The block context.
+ * @param fh The config render lambda to execute.
+ * @param codeWithInfo The block's code and feature flags.
+ * @param configKey A key for the configuration, used for cache busting.
+ * @param ops Options for the computable.
+ * @returns A `Computable` that will resolve to the result of the lambda execution.
+ */
 export function computableFromRF(
   env: MiddleLayerEnvironment,
   ctx: BlockContextAny,
@@ -27,59 +84,70 @@ export function computableFromRF(
       console.log(`Block lambda recalculation : ${key} (${cCtx.changeSourceMarker}; ${cCtx.bodyInvocations} invocations)`);
 
     const scope = new Scope();
-    cCtx.addOnDestroy(() => scope.dispose());
-
-    const runtime = scope.manage(env.quickJs.newRuntime());
-    runtime.setMemoryLimit(1024 * 1024 * 8);
-    runtime.setMaxStackSize(1024 * 320);
-
-    let deadlineSettings: DeadlineSettings | undefined;
-    runtime.setInterruptHandler(() => {
-      if (deadlineSettings === undefined) return false;
-      if (Date.now() > deadlineSettings.deadline) return true;
-      return false;
+    let keepVmAlive = false;
+    cCtx.addOnDestroy(() => {
+      // If keepVmAlive is false, the scope will be disposed by the finally block,
+      // no need to dispose it here.
+      if (keepVmAlive) scope.dispose();
     });
-    const vm = scope.manage(runtime.newContext());
-    const rCtx = new JsExecutionContext(scope, vm,
-      (s) => { deadlineSettings = s; },
-      featureFlags,
-      { computableCtx: cCtx, blockCtx: ctx, mlEnv: env });
-
-    rCtx.evaluateBundle(code.content);
-    const result = rCtx.runCallback(fh.handle);
-
-    rCtx.resetComputableCtx();
-
-    let recalculationCounter = 0;
-
-    if (getDebugFlags().logOutputStatus === 'any')
-      console.log(`Output ${fh.handle} scaffold calculated.`);
 
-    return {
-      ir: rCtx.computableHelper!.computablesToResolve,
-      postprocessValue: (resolved: Record<string, unknown>, { unstableMarker, stable }) => {
+    try {
+      const runtime = scope.manage(env.quickJs.newRuntime());
+      runtime.setMemoryLimit(1024 * 1024 * 8);
+      runtime.setMaxStackSize(1024 * 320);
+
+      let deadlineSettings: DeadlineSettings | undefined;
+      runtime.setInterruptHandler(() => {
+        if (deadlineSettings === undefined) return false;
+        if (Date.now() > deadlineSettings.deadline) return true;
+        return false;
+      });
+      const vm = scope.manage(runtime.newContext());
+      const rCtx = new JsExecutionContext(scope, vm,
+        (s) => { deadlineSettings = s; },
+        featureFlags,
+        { computableCtx: cCtx, blockCtx: ctx, mlEnv: env });
+
+      rCtx.evaluateBundle(code.content);
+      const result = rCtx.runCallback(fh.handle);
+
+      rCtx.resetComputableCtx();
+
+      const toBeResolved = rCtx.computableHelper!.computablesToResolve;
+
+      if (Object.keys(toBeResolved).length === 0) {
+        const importedResult = rCtx.importObjectUniversal(result);
+        logOutputStatus(fh.handle, importedResult, cCtx.unstableMarker === undefined, -1, cCtx.unstableMarker);
+        return { ir: importedResult };
+      }
+
+      let recalculationCounter = 0;
+      if (getDebugFlags().logOutputStatus)
+        console.log(`Output ${fh.handle} scaffold calculated (not all computables resolved yet).`);
+      keepVmAlive = true;
+
+      return {
+        ir: toBeResolved,
+        postprocessValue: (resolved: Record<string, unknown>, { unstableMarker, stable }) => {
         // resolving futures
-        for (const [handle, value] of Object.entries(resolved)) rCtx.runCallback(handle, value);
-
-        // rendering result
-        const renderedResult = rCtx.importObjectUniversal(result);
-
-        // logging
-        recalculationCounter++;
-        if (getDebugFlags().logOutputStatus && (getDebugFlags().logOutputStatus === 'any' || !stable)) {
-          if (stable)
-            console.log(
-              `Stable output ${fh.handle} calculated ${renderedResult !== undefined ? 'defined' : 'undefined'}; (#${recalculationCounter})`,
-            );
-          else
-            console.log(
-              `Unstable output ${fh.handle}; marker = ${unstableMarker}; ${renderedResult !== undefined ? 'defined' : 'undefined'} (#${recalculationCounter})`,
-            );
-        }
-
-        return renderedResult;
-      },
-    };
+          for (const [handle, value] of Object.entries(resolved)) rCtx.runCallback(handle, value);
+
+          // rendering result
+          const renderedResult = rCtx.importObjectUniversal(result);
+
+          // logging
+          recalculationCounter++;
+          logOutputStatus(fh.handle, renderedResult, stable, recalculationCounter, unstableMarker);
+
+          return renderedResult;
+        },
+      };
+    } catch (e) {
+      keepVmAlive = false;
+      throw e;
+    } finally {
+      if (!keepVmAlive) scope.dispose();
+    }
   }, ops);
 }