@uipath/maestro-builder-sdk 6.8.0 → 6.8.1

package/dist/check.js

@@ -1250,7 +1250,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
             const declared = specs?.[named];
             const by = value.__lookup.by;
             if (declared && typeof by === 'string' && !declared.by.includes(by)) {
-                const { target, call } = lookupPhrases(named, declared);
+                const { target, call } = lookupPhrases(named, declared, spec);
                 diags.push({
                     level: 'error',
                     code: 'LOOKUP_UNKNOWN_MATCH_KEY',
@@ -1302,7 +1302,7 @@ function checkConnectorLookups(step, spec, opts, diags) {
         const literal = value instanceof Expr ? value.value : value;
         if (typeof literal !== 'string')
             return;
-        const { target, call } = lookupPhrases(field, lookup);
+        const { target, call } = lookupPhrases(field, lookup, spec);
         diags.push({
             level: 'warning',
             code: 'LOOKUP_LITERAL_ID',
@@ -1439,13 +1439,32 @@ function checkConnectorContract(step, spec, opts, diags) {
         }
     }
 }
-/** The two phrases every lookup diagnostic needs: what the field sends, and how to resolve it. */
-function lookupPhrases(field, lookup) {
+/**
+ * The two phrases every lookup diagnostic needs: what the field sends, and how
+ * to resolve it.
+ *
+ * The `call` names BOTH authoring forms, and names which one the alias belongs
+ * to. Printing `lookup(<Descriptor>, 'entityName').byDisplayName('<value>')`
+ * alone — the old text — was a remedy with an unstated precondition: aliases
+ * are generated onto the descriptor, and `<Descriptor>` is a placeholder the
+ * reader has to fill from somewhere. An author holding the connector key and
+ * action instead (the form the library's Generic CRUD half is authored in, and
+ * the majority of its lookup fields) substitutes those for the placeholder,
+ * keeps the alias, and gets `lookup(...).byDisplayName is not a function`. Six
+ * flow-eval tasks did precisely that, each losing a check-edit-check round to
+ * a message that had told them to.
+ */
+function lookupPhrases(field, lookup, spec) {
     const target = `${lookup.objectName ?? lookup.path}.${lookup.value}`;
+    const by = lookup.by[0] ?? 'id';
     const alias = Object.keys(lookup.aliases)[0];
+    // The key/action form first: it needs no import, so it is the one line that
+    // is paste-ready from the message alone.
+    const generic = `lookup('${spec.key}', '${spec.action}', '${field}').by('${by}', '<value>')`;
     const call = alias
-        ? `lookup(<Descriptor>, '${field}').${alias}('<value>')`
-        : `lookup(<Descriptor>, '${field}').by('${lookup.by[0] ?? 'id'}', '<value>')`;
+        ? `${generic}\n  or \`lookup(D, '${field}').${alias}('<value>')\`, where D is the `
+            + `descriptor \`${prepareCommand(spec.key, spec.action)}\` generates — the aliases exist only there`
+        : generic;
     return { target, call };
 }
 /**
@@ -1502,7 +1521,7 @@ function runtimeLookupDiagnostic(step, spec, field, lookup, value) {
         || leaf.toLowerCase() === valueLeaf.toLowerCase()
         || (valueIsEmail && EMAIL_LEAF.test(leaf))))
         return undefined;
-    const { target, call } = lookupPhrases(field, lookup);
+    const { target, call } = lookupPhrases(field, lookup, spec);
     const searchesByEmail = lookup.by.some((b) => EMAIL_LEAF.test(b));
     const isEmail = !!leaf && EMAIL_LEAF.test(leaf) && !valueIsEmail && !searchesByEmail;
     const message = `Connector step "${step}": \`${field}\` is a lookup field bound to the runtime expression `

package/dist/core/lookups.js

@@ -46,7 +46,53 @@ export function isLookupToken(v) {
 export function lookupKey(nodeType, field, by, value) {
     return JSON.stringify([nodeType, field, by, value]);
 }
-function makeBuilder(nodeType, field, spec) {
+/**
+ * An alias-shaped property: `byEmail`, `byDisplayName`, `byAccountId`.
+ *
+ * Narrow on purpose. The builder is handed to whatever inspects it next —
+ * `util.inspect`, a `then` probe on an accidental `await`, a spread — and a
+ * trap that answered for EVERY absent name would turn those into throws. Only
+ * a name the author could have meant as an alias is intercepted.
+ */
+const ALIAS_SHAPE = /^by[A-Z]/;
+/**
+ * Why `.byDisplayName()` is absent, in the terms of the form that was used.
+ *
+ * Aliases are generated from the descriptor's own `lookups` table, so the
+ * string form — which has no table to read — offers only `.by(name, value)`.
+ * That is a deliberate trade (see the overload's `@remarks`), but the author
+ * who trips it learns it as `lookup(...).byDisplayName is not a function`: a
+ * bare `TypeError` naming neither the field, the form, nor the way out. Six
+ * flow-eval tasks lost turns to exactly that message, every one of them having
+ * copied an alias out of a diagnostic or a descriptor's doc comment and pasted
+ * it onto the key/action form they happened to be holding.
+ */
+function missingAliasMessage(nodeType, field, alias, spec, generic) {
+    const head = `lookup(${nodeType}, '${field}'): \`.${alias}()\` does not exist. `;
+    if (!spec) {
+        // The remedy names the author's OWN key and action rather than a
+        // placeholder: a remedy with a hole in it is what produced this call.
+        const here = generic
+            ? `lookup('${generic.key}', '${generic.action}', '${field}')`
+            : `lookup(…, '${field}')`;
+        return head
+            + `Aliases are generated onto the descriptor, and this call has no descriptor `
+            + `to read them from, so only \`.by(name, value)\` exists here. Search by name:\n`
+            + `  ${here}.by('<searchable name>', <value>)\n`
+            + `\`check\` and \`${prepareCommand()}\` both print the names this field is `
+            + `searchable by. Or import the descriptor `
+            + (generic ? `\`${prepareCommand(generic.key, generic.action)}\` generates ` : '')
+            + `and call \`.${alias}(<value>)\` on that.`;
+    }
+    const aliases = Object.keys(spec.aliases);
+    return head
+        + (aliases.length
+            ? `Generated aliases for this field: ${aliases.map((a) => `\`.${a}()\``).join(', ')}. `
+            : `This field earns no alias — two of its names camelise to one, so both were dropped. `)
+        + `Every searchable name is reachable as `
+        + `\`.by(${spec.by.map((b) => `'${b}'`).join(' | ')}, <value>)\`.`;
+}
+function makeBuilder(nodeType, field, spec, generic) {
     const token = (by, value) => ({ __lookup: { nodeType, field, by, value } });
     const builder = {
         by(name, value) {
@@ -63,7 +109,19 @@ function makeBuilder(nodeType, field, spec) {
     for (const [alias, byName] of Object.entries(spec?.aliases ?? {})) {
         builder[alias] = (value) => token(byName, value);
     }
-    return builder;
+    // The throw is deferred to the CALL rather than raised on the property read,
+    // so the stack points at `.byDisplayName('Inbox')` — the line the author
+    // wrote — instead of at the property access the engine desugared it into.
+    return new Proxy(builder, {
+        get(target, prop, receiver) {
+            if (typeof prop === 'string' && !(prop in target) && ALIAS_SHAPE.test(prop)) {
+                return () => {
+                    throw new Error(missingAliasMessage(nodeType, field, prop, spec, generic));
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
 }
 export function lookup(a, b, c) {
     if (typeof a === 'string') {
@@ -71,7 +129,7 @@ export function lookup(a, b, c) {
             throw new Error("lookup(key, action, field) needs all three arguments; " +
                 "did you mean lookup(descriptor, field)?");
         }
-        return makeBuilder(`uipath.connector.${a}.${b}`, c);
+        return makeBuilder(`uipath.connector.${a}.${b}`, c, undefined, { key: a, action: b });
     }
     if (!('nodeType' in a) || a.nodeType === undefined) {
         const event = a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.8.0",
+  "version": "6.8.1",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -87,5 +87,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "de2812e18734552a112d97deec05fc9ae2244caa"
+  "gitref": "5ec4e9cb4aeac6a5297078cfd071d7c38784fed3"
 }