@uipath/maestro-builder-sdk 6.59.0 → 6.60.0

package/dist/nodes/script/flow/runtime.js

@@ -1,9 +1,41 @@
 /**
- * What a Flow script body can read: the language's ES2020 built-ins, `console`,
- * and the runtime's `$vars`. From the Flow skill's `references/script.md` ("The
- * JavaScript runtime"), which also lists what reads `undefined` in a real run and
- * is therefore absent here: `Intl`, `URL`, `TextEncoder`, `Buffer`, `fetch`,
- * `require`, `structuredClone`. Change this when the runtime changes.
+ * The names the engine's preludes declare with `const` before the script runs
+ * (`ScriptTaskService.cs`, `WithBuiltInFunctions` and `WithConsole`). At the
+ * body's top level, a `const`, `let`, `var`, `function` or `class` of one fails
+ * with "Identifier '…' has already been declared", and an assignment to one with
+ * "Assignment to constant variable." (both measured on Jint 4.4.0). Inside a
+ * nested block or function the name is the author's own and is fine.
+ */
+const FLOW_SCRIPT_CONST_GLOBALS = new Set(['console', 'uipath', 'aggregate', '_aggregate', '_pipe']);
+/**
+ * The members the engine's own objects have; any other member reads
+ * `undefined`, so calling it throws "Property '…' of object is not a function"
+ * (measured on Jint 4.4.0). `crypto` holds only `randomUUID`
+ * (`JavaScriptEvaluator.cs`), and `console` only the five no-ops `WithConsole`
+ * declares (`ScriptTaskService.cs`).
+ */
+const FLOW_SCRIPT_GLOBAL_MEMBERS = new Map([
+    ['crypto', new Set(['randomUUID'])],
+    ['console', new Set(['debug', 'error', 'info', 'log', 'warn'])],
+]);
+/**
+ * What a Flow script body can read: the language's ES2020 built-ins, the
+ * globals the engine registers, `console`, and the runtime's `$vars`.
+ *
+ * Measured against UiPath/PO.BpmnEngine, which runs a script body with
+ * Jint 4.4.0 (`ScriptTaskService.InvokeScriptAsync`,
+ * `src/BpmnEngine/UiPath.PO.Worker/Services/ElementExecution/Script/ScriptTaskService.cs`):
+ * the body goes to `Engine.Evaluate` as a script, after `btoa`/`atob` (UTF-8),
+ * `randomUUID` and `crypto` (holding only `randomUUID`) are set
+ * (`src/BpmnEngine/UiPath.PO.BpmnEngine/Expressions/JavaScriptEvaluator.cs`) and
+ * two preludes declare {@link FLOW_SCRIPT_CONST_GLOBALS} with `const`. `Intl`,
+ * `URL`, `TextEncoder`, `Buffer`, `fetch`, `require` and `structuredClone` read
+ * `undefined` there, so they are absent here. Change this when the engine does.
+ *
+ * `aggregate`, `_aggregate`, `_pipe` and `uipath` exist but are the engine's
+ * undocumented helpers, so a script function may not read them; it may not
+ * redeclare or assign them either (`constGlobals`). Of `crypto` and `console`
+ * it may read only the members the engine's have (`globalMembers`).
  *
  * Annex B's `escape`/`unescape` are left off on purpose: they URL-encode, and
  * `escape` is the likeliest name for an author's own HTML-escape helper, which
@@ -15,8 +47,11 @@
 export const FLOW_SCRIPT_RUNTIME = {
     scopeGlobal: '$vars',
     name: 'the Flow script runtime',
+    constGlobals: FLOW_SCRIPT_CONST_GLOBALS,
+    globalMembers: FLOW_SCRIPT_GLOBAL_MEMBERS,
     globals: new Set([
         'undefined', 'NaN', 'Infinity', 'globalThis', 'console',
+        'btoa', 'atob', 'randomUUID', 'crypto',
         'Object', 'Function', 'Array', 'Number', 'Boolean', 'String', 'Symbol', 'BigInt', 'Date', 'RegExp', 'Math', 'JSON',
         'Promise', 'Proxy', 'Reflect', 'Map', 'Set', 'WeakMap', 'WeakSet',
         'Error', 'EvalError', 'RangeError', 'ReferenceError', 'SyntaxError', 'TypeError', 'URIError',

package/dist/script-globals.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The globals the Flow script runtime gives a script body beyond the language,
+ * as types, for a `.flow.ts` that type-checks its script functions.
+ *
+ * Opt in from the file that uses them:
+ *
+ * ```ts
+ * /// <reference types="@uipath/maestro-builder-sdk/script-globals" />
+ * ```
+ *
+ * Types only. A script function is never called in Node; its body runs on the
+ * engine, which provides these names (UiPath/PO.BpmnEngine,
+ * `src/BpmnEngine/UiPath.PO.BpmnEngine/Expressions/JavaScriptEvaluator.cs`).
+ * Importing an implementation instead would not work: `compile` refuses a script
+ * function that reads a name from its module.
+ *
+ * Opt-in rather than part of the package entry, so importing the SDK does not
+ * add globals to every program that does.
+ *
+ * `btoa` and `atob` repeat the signatures `@types/node` and the DOM library
+ * declare, so they merge with either; they are here for a program that has
+ * neither. Note the engine's are UTF-8, where Node's and the browser's are
+ * Latin-1 and throw on a character above U+00FF. `crypto` is not declared:
+ * the engine's holds only `randomUUID`, and both of those libraries already
+ * type `crypto.randomUUID()`.
+ */
+export {};
+declare global {
+    /** A fresh lowercase, hyphenated v4 UUID. The engine also exposes it as `crypto.randomUUID`. */
+    function randomUUID(): string;
+    /** Base64 of a string's UTF-8 bytes, in the engine (Node's and the browser's take Latin-1). */
+    function btoa(data: string): string;
+    /** The string whose UTF-8 bytes a Base64 string encodes, in the engine. */
+    function atob(data: string): string;
+}

package/dist/script-globals.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.59.0",
+  "version": "6.60.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -37,6 +37,10 @@
       "types": "./dist/cli/index.d.ts",
       "import": "./dist/cli/index.js"
     },
+    "./script-globals": {
+      "types": "./dist/script-globals.d.ts",
+      "import": "./dist/script-globals.js"
+    },
     "./registry-materializer": {
       "types": "./dist/registry/materializer.d.ts",
       "import": "./dist/registry/materializer.js"
@@ -96,5 +100,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "ddebc637dab91373bb326fd4da5590f6e7d3b9c2"
+  "gitref": "d9059695caec0a3b1f3b215f5b830451dbdbdad9"
 }