@uipath/maestro-builder-sdk 6.25.1 → 6.27.0

package/dist/serialize.js

@@ -19,7 +19,8 @@ import { planContributionBindings } from './core/contribution-bindings.js';
 import { declaredErrorPortRefusal, definitionHasErrorPort, errorPortRefusal } from './core/error-port.js';
 import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
-import { resolveVersion } from './core/nodes/versioned.js';
+import { resolveVersionCarried } from './core/nodes/versioned.js';
+import { indexCarriedDefinitions } from './core/carried-definitions.js';
 import { FORM_FIELD_JSON_TYPE } from './core/form-field-type.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
@@ -2271,8 +2272,8 @@ function declaresMemoryHandle(def) {
  * compiles. The corpus also carries 1.1 and 1.3; `shared/sample-flows/
  * inline-agent.flow` says 1.0, which appears in none of the 29.
  */
-function inlineAgentDef(version, withMemory) {
-    const bundled = DEFS[`${INLINE_AGENT_TYPE}@${version}`];
+function inlineAgentDef(version, withMemory, resolve = (t, v) => DEFS[`${t}@${v}`]) {
+    const bundled = resolve(INLINE_AGENT_TYPE, version);
     if (!bundled)
         return undefined;
     const def = jsonClone(bundled);
@@ -4240,6 +4241,17 @@ function stepNamesOf(steps, out = []) {
     return out;
 }
 export function serialize(built, opts = {}) {
+    /**
+     * Definitions the flow carries (`.definitions()`, #1128), by `type@version` —
+     * the third source a pinned `{ version }` resolves from, after the bundle and
+     * the node-type registry. A flow that carries nothing compiles exactly as
+     * before. A subflow body sees its own carried definitions plus its
+     * ancestors' (as `check` does), only while it is emitted.
+     */
+    let carriedDefs = indexCarriedDefinitions(built.definitions ?? [], `flow "${built.id}" .definitions()`);
+    const carriedFor = Object.assign((type, version) => carriedDefs.get(`${type}@${version}`), { versions: (type) => [...carriedDefs.keys()].filter((k) => k.startsWith(`${type}@`)).map((k) => k.slice(type.length + 1)) });
+    /** The exact definition of `type@version`: bundled, else carried, else `undefined`. */
+    const definitionFor = (type, version) => DEFS[`${type}@${version}`] ?? carriedFor(type, version);
     /**
      * The `definitions[]` a flow carries, keyed by `type@version` — NOT by type.
      * One flow can legitimately hold two versions of the same family (a plain
@@ -4451,19 +4463,22 @@ export function serialize(built, opts = {}) {
     function makeNode(type, id, label, o = {}) {
         let def = o.def ?? defByType.get(type);
         if (o.requestedVersion !== undefined && def?.version !== o.requestedVersion) {
-            const exact = o.def ? undefined : DEFS[`${type}@${o.requestedVersion}`];
+            const exact = o.def ? undefined : definitionFor(type, o.requestedVersion);
             if (!exact) {
-                // Name every version the SDK could have resolved: every bundled
-                // version of the type, else (a type built per resource, a connector)
-                // the definition in hand. Naming only the default sent the reader
-                // looking for a version that was shipped all along (#1128:
+                // Name every version the SDK could have resolved: every bundled or
+                // carried version of the type, else (a type built per resource, a
+                // connector) the definition in hand. Naming only the default sent the
+                // reader looking for a version that was shipped all along (#1128:
                 // quick-form bundles 1.0 AND 1.1, and the message said 1.0).
-                const bundled = bundledVersions(type);
-                const resolvable = bundled.length > 0 ? bundled
+                const prefix = `${type}@`;
+                const carriedVersions = [...carriedDefs.keys()].filter((k) => k.startsWith(prefix)).map((k) => k.slice(prefix.length));
+                const known = o.def ? [] : [...bundledVersions(type), ...carriedVersions];
+                const resolvable = known.length > 0 ? known
                     : [def?.version].filter((v) => typeof v === 'string');
                 throw new Error(`"${label ?? id}" requests ${type}@${o.requestedVersion}, but this SDK resolves only `
                     + `${type}@${resolvable.join(', ') || '<none>'}. Versions are exact — omit { version } to use `
-                    + `the pinned default, or request a version this SDK ships.`);
+                    + `the pinned default, request a version this SDK ships, or carry that version's definition `
+                    + `(the .flow file's definitions[] entry) with .definitions([...]).`);
             }
             def = exact;
         }
@@ -4532,6 +4547,16 @@ export function serialize(built, opts = {}) {
      * a null. It is emitted here, always, so it cannot be forgotten.
      */
     function emitSubflowBody(child, nodeId) {
+        const outer = carriedDefs;
+        carriedDefs = indexCarriedDefinitions(child.definitions ?? [], `subflow "${nodeId}" .definitions()`, new Map(outer));
+        try {
+            return emitSubflowBodyIn(child, nodeId);
+        }
+        finally {
+            carriedDefs = outer;
+        }
+    }
+    function emitSubflowBodyIn(child, nodeId) {
         const childGlobals = emittableGlobals(child, `subflow "${nodeId}"`, 'subflow');
         const scope = newScope(childGlobals.outputs, childGlobals.vars, childGlobals.backing, childGlobals.backingReads);
         // Claim this copy's node ids UP FRONT, so the rename map is complete before
@@ -4807,7 +4832,11 @@ export function serialize(built, opts = {}) {
     function emitRegistered(entry, step, tails, scope, parentId) {
         const where = `step "${step.name}"`;
         const spec = step.spec;
-        const impl = resolveVersion(entry.type, spec, step.options?.version, where);
+        // A pin the registry has no implementation for, but the flow carries, is
+        // emitted at that version with the carried definition (#1128).
+        const resolved = resolveVersionCarried(entry.type, spec, step.options?.version, where, carriedFor);
+        const impl = resolved.impl;
+        const version = resolved.version;
         const id = stepUid(scope, step.name);
         // As for every typed family: record the failure-envelope boundary before any
         // expression renders, so a handler reading this step resolves correctly.
@@ -4817,14 +4846,19 @@ export function serialize(built, opts = {}) {
             step: step.name,
             nodeId: id,
             flowId: built.id,
-            version: impl.version,
+            version,
             pinnedVersion: step.options?.version,
             render: (value) => renderValue(value, scope.rename),
             renameRefs: (js) => renameRefs(js, scope.rename),
             stepNodeId: (name) => scope.stepNodeId.get(name) ?? name,
             mint: (seed) => stableId(`${built.id}:${id}:${seed}`),
             bind: (b) => { bound.push(b); },
-            definition: (typeName, version) => bundledDefinition(typeName, version),
+            // At a carried version the node's own definition IS the carried one,
+            // whatever version the implementation asks for (it was written for a
+            // bundled one), so its defaults and outputs come from the file's entry.
+            definition: (typeName, v) => (resolved.carried !== undefined && typeName === impl.typeName
+                ? resolved.carried
+                : bundledDefinition(typeName, v) ?? carriedFor(typeName, v)),
             bindings: resourceBindings,
             resolveBinding: (name, attribute, at) => resolveBinding(opts, name, attribute, at),
             bindConnection: (c) => {
@@ -4843,26 +4877,31 @@ export function serialize(built, opts = {}) {
         // The definition contract, both halves: a per-tenant type supplies its
         // definition, and a bundled type does not (its definition is the bundle's, and
         // makeNode records it, so the error-edge refusal and check ask the same one).
-        let def;
+        let def = resolved.carried;
         if (impl.definition === 'bundled' && contribution.definition !== undefined) {
-            throw new Error(`internal SDK error: ${where}: bundled node type ${impl.typeName}@${impl.version} returned a definition; `
+            throw new Error(`internal SDK error: ${where}: bundled node type ${impl.typeName}@${version} returned a definition; `
                 + 'the bundle owns it — omit `definition`, or declare the type per-tenant.');
         }
+        // A per-tenant type builds its definition from `ctx.definition(type, version)`,
+        // which answers with the carried definition at a carried version, so the
+        // contribution's own definition wins: it is the carried template plus this
+        // instance's edits (a queue step's own resourceKey, for instance). Only a type
+        // that supplies none at a carried version takes the carried definition as is.
         if (contribution.definition !== undefined) {
-            def = resolveContributionDefinition(contribution.definition, impl.version, where);
+            def = resolveContributionDefinition(contribution.definition, version, where);
         }
-        else if (impl.definition === 'per-tenant') {
-            throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${impl.version} returned no definition.`);
+        else if (impl.definition === 'per-tenant' && resolved.carried === undefined) {
+            throw new Error(`internal SDK error: ${where}: per-tenant node type ${impl.typeName}@${version} returned no definition.`);
         }
         if (impl.definition === 'per-tenant') {
             const port = typeof impl.errorPort === 'function' ? impl.errorPort(spec) : impl.errorPort === true;
             // The declaration answers for check, which has no definition; here the
             // definition is in hand, and the two must agree (#1011).
             if (port && def !== undefined && !definitionHasErrorPort(def)) {
-                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${impl.version} declares an error port, `
+                throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} declares an error port, `
                     + 'but the definition it supplied has no error handle and no supportsErrorHandling.');
             }
-            declaredErrorPorts.set(id, { port, typeName: impl.typeName, version: impl.version });
+            declaredErrorPorts.set(id, { port, typeName: impl.typeName, version });
         }
         // A forward port is a handle the definition declares, one of the type's
         // author-named exits, or one the product derives (`derivesPort`: a human
@@ -4871,13 +4910,17 @@ export function serialize(built, opts = {}) {
         const exitPorts = new Set(exits && hasExits(exits) ? exits.map((e) => e.port) : []);
         for (const p of [...(contribution.port !== undefined ? [contribution.port] : []), ...(contribution.fanOut ?? []).map((f) => f.port)]) {
             if (exitPorts.has(p) || impl.derivesPort?.(spec, p)
-                || declaresForwardPort(def ?? bundledDefinition(impl.typeName, impl.version), p))
+                || declaresForwardPort(def ?? bundledDefinition(impl.typeName, version), p))
                 continue;
-            throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${impl.version} leaves by port "${p}", `
+            throw new Error(`internal SDK error: ${where}: node type ${impl.typeName}@${version} leaves by port "${p}", `
                 + 'which its definition declares no source handle for, and the type neither lists as an exit nor derives.');
         }
+        // A carried definition answers the error-edge refusal as a bundled one does
+        // (makeNode records only the definitions it resolved itself).
+        if (resolved.carried !== undefined)
+            bundledNodeDefs.set(id, def ?? resolved.carried);
         return placeStepNode({
-            where, stepName: step.name, id, typeName: impl.typeName, requestedVersion: impl.version, def, contribution, bound, tails, scope, parentId,
+            where, stepName: step.name, id, typeName: impl.typeName, requestedVersion: version, def, contribution, bound, tails, scope, parentId,
             trackOutcomes: true,
         });
     }
@@ -5041,11 +5084,12 @@ export function serialize(built, opts = {}) {
             // agent attaches memory keeps the handle for all of them.
             const withMemory = s.memory !== undefined
                 || declaresMemoryHandle(emittedDefs.get(`${INLINE_AGENT_TYPE}@${version}`));
-            const def = inlineAgentDef(version, withMemory);
+            const def = inlineAgentDef(version, withMemory, definitionFor);
             if (!def) {
                 throw new Error(`"${step.name}" requests ${INLINE_AGENT_TYPE}@${version}, but this SDK resolves only `
                     + `${INLINE_AGENT_VERSIONS.map((v) => `${INLINE_AGENT_TYPE}@${v}`).join(', ')}. Versions are exact — `
-                    + `omit { version } to use the default (${INLINE_AGENT_DEFAULT_VERSION}), or request a version this SDK ships.`);
+                    + `omit { version } to use the default (${INLINE_AGENT_DEFAULT_VERSION}), request a version this SDK ships, `
+                    + `or carry that version's definition with .definitions([...]).`);
             }
             if (s.memory !== undefined && !declaresMemoryHandle(def)) {
                 throw new Error(`"${step.name}" attaches \`memory\`, but ${INLINE_AGENT_TYPE}@${version} declares no \`memory\` handle. `
@@ -6127,8 +6171,12 @@ export function serialize(built, opts = {}) {
                 // must leave from ITS handles), else positional (#1130).
                 const cases = step.cases.map((c, i) => ({
                     id: c.id ?? `case_${i + 1}`,
-                    label: c.label ?? `Case ${caseLiteral(c.value)}`,
-                    expression: `${renameRefs(step.on.js, scope.rename)} === ${caseLiteral(c.value)}`,
+                    // A `when` case writes its own condition — the product's per-case form,
+                    // first truthy case wins (#1131). A `value` case compares with `on`.
+                    label: c.label ?? (c.when !== undefined ? `Case ${i + 1}` : `Case ${caseLiteral(c.value)}`),
+                    expression: c.when !== undefined
+                        ? renameRefs(c.when.js, scope.rename)
+                        : `${renameRefs(step.on?.js ?? 'undefined', scope.rename)} === ${caseLiteral(c.value)}`,
                 }));
                 node.inputs = { cases, hasDefault: step.default !== undefined };
                 scope.nodes.push(node);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.25.1",
+  "version": "6.27.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -92,5 +92,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "384f76113bc43067b5ec5ea700534e9611e664ff"
+  "gitref": "69352e3f5c7c379e0e70b3c7b6fb2fba91255f84"
 }