n8n-workflow 1.98.0 → 1.99.0

package/dist/{workflow-data-proxy.js → esm/workflow-data-proxy.js}

@@ -1,56 +1,23 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WorkflowDataProxy = void 0;
-const jmespath = __importStar(require("jmespath"));
-const luxon_1 = require("luxon");
-const augment_object_1 = require("./augment-object");
-const constants_1 = require("./constants");
-const application_error_1 = require("./errors/application.error");
-const expression_error_1 = require("./errors/expression.error");
-const global_state_1 = require("./global-state");
-const interfaces_1 = require("./interfaces");
-const NodeHelpers = __importStar(require("./node-helpers"));
-const result_1 = require("./result");
-const type_guards_1 = require("./type-guards");
-const utils_1 = require("./utils");
-const workflow_data_proxy_env_provider_1 = require("./workflow-data-proxy-env-provider");
-const workflow_data_proxy_helpers_1 = require("./workflow-data-proxy-helpers");
+/* eslint-disable @typescript-eslint/prefer-nullish-coalescing */
+/* eslint-disable @typescript-eslint/no-this-alias */
+/* eslint-disable @typescript-eslint/no-unsafe-return */
+import * as jmespath from 'jmespath';
+import { DateTime, Duration, Interval, Settings } from 'luxon';
+import { augmentArray, augmentObject } from './augment-object';
+import { AGENT_LANGCHAIN_NODE_TYPE, SCRIPTING_NODE_TYPES } from './constants';
+import { ApplicationError } from './errors/application.error';
+import { ExpressionError } from './errors/expression.error';
+import { getGlobalState } from './global-state';
+import { NodeConnectionTypes } from './interfaces';
+import * as NodeHelpers from './node-helpers';
+import { createResultError, createResultOk } from './result';
+import { isResourceLocatorValue } from './type-guards';
+import { deepCopy, isObjectEmpty } from './utils';
+import { createEnvProvider, createEnvProviderState } from './workflow-data-proxy-env-provider';
+import { getPinDataIfManualExecution } from './workflow-data-proxy-helpers';
 const isScriptingNode = (nodeName, workflow) => {
     const node = workflow.getNode(nodeName);
-    return node && constants_1.SCRIPTING_NODE_TYPES.includes(node.type);
+    return node && SCRIPTING_NODE_TYPES.includes(node.type);
 };
 const PAIRED_ITEM_METHOD = {
     PAIRED_ITEM: 'pairedItem',
@@ -58,7 +25,23 @@ const PAIRED_ITEM_METHOD = {
     ITEM: 'item',
     $GET_PAIRED_ITEM: '$getPairedItem',
 };
-class WorkflowDataProxy {
+export class WorkflowDataProxy {
+    workflow;
+    runIndex;
+    itemIndex;
+    activeNodeName;
+    siblingParameters;
+    mode;
+    additionalKeys;
+    executeData;
+    defaultReturnRunIndex;
+    selfData;
+    contextNodeName;
+    envProviderState;
+    runExecutionData;
+    connectionInputData;
+    timezone;
+    // TODO: Clean that up at some point and move all the options into an options object
     constructor(workflow, runExecutionData, runIndex, itemIndex, activeNodeName, connectionInputData, siblingParameters, mode, additionalKeys, executeData, defaultReturnRunIndex = -1, selfData = {}, contextNodeName = activeNodeName, envProviderState) {
         this.workflow = workflow;
         this.runIndex = runIndex;
@@ -74,23 +57,29 @@ class WorkflowDataProxy {
         this.envProviderState = envProviderState;
         this.runExecutionData = isScriptingNode(this.contextNodeName, workflow)
             ? runExecutionData !== null
-                ? (0, augment_object_1.augmentObject)(runExecutionData)
+                ? augmentObject(runExecutionData)
                 : null
             : runExecutionData;
         this.connectionInputData = isScriptingNode(this.contextNodeName, workflow)
-            ? (0, augment_object_1.augmentArray)(connectionInputData)
+            ? augmentArray(connectionInputData)
             : connectionInputData;
-        this.timezone = workflow.settings?.timezone ?? (0, global_state_1.getGlobalState)().defaultTimezone;
-        luxon_1.Settings.defaultZone = this.timezone;
+        this.timezone = workflow.settings?.timezone ?? getGlobalState().defaultTimezone;
+        Settings.defaultZone = this.timezone;
     }
+    /**
+     * Returns a proxy which allows to query context data of a given node
+     *
+     * @private
+     * @param {string} nodeName The name of the node to get the context from
+     */
     nodeContextGetter(nodeName) {
         const that = this;
         const node = this.workflow.nodes[nodeName];
         if (!that.runExecutionData?.executionData && that.connectionInputData.length > 0) {
-            return {};
+            return {}; // incoming connection has pinned data, so stub context object
         }
         if (!that.runExecutionData?.executionData && !that.runExecutionData?.resultData) {
-            throw new expression_error_1.ExpressionError("The workflow hasn't been executed yet, so you can't reference any context data", {
+            throw new ExpressionError("The workflow hasn't been executed yet, so you can't reference any context data", {
                 runIndex: that.runIndex,
                 itemIndex: that.itemIndex,
                 type: 'no_execution_data',
@@ -100,6 +89,7 @@ class WorkflowDataProxy {
             has: () => true,
             ownKeys(target) {
                 if (Reflect.ownKeys(target).length === 0) {
+                    // Target object did not get set yet
                     Object.assign(target, NodeHelpers.getContext(that.runExecutionData, 'node', node));
                 }
                 return Reflect.ownKeys(target);
@@ -148,12 +138,12 @@ class WorkflowDataProxy {
             .find((nodeProperty) => nodeProperty.name === 'operation' &&
             nodeProperty.displayOptions?.show?.resource?.some((y) => y === resourceKey))
             ?.options?.find((y) => 'value' in y && y.value === operationKey)?.name ?? null;
-        const hasCredentials = !(0, utils_1.isObjectEmpty)(node.credentials ?? {});
+        const hasCredentials = !isObjectEmpty(node.credentials ?? {});
         const hasValidCalendar = nodeType.description.name.includes('googleCalendar')
-            ? (0, type_guards_1.isResourceLocatorValue)(node.parameters.calendar) && node.parameters.calendar.value !== ''
+            ? isResourceLocatorValue(node.parameters.calendar) && node.parameters.calendar.value !== ''
             : undefined;
         const aiDefinedFields = Object.entries(node.parameters)
-            .map(([key, value]) => [key, (0, type_guards_1.isResourceLocatorValue)(value) ? value.value : value])
+            .map(([key, value]) => [key, isResourceLocatorValue(value) ? value.value : value])
             .filter(([_, value]) => value?.toString().toLowerCase().includes('$fromai'))
             .map(([key]) => nodeType.description.properties.find((property) => property.name === key)?.displayName);
         return {
@@ -168,18 +158,18 @@ class WorkflowDataProxy {
     }
     agentInfo() {
         const agentNode = this.workflow.getNode(this.activeNodeName);
-        if (!agentNode || agentNode.type !== constants_1.AGENT_LANGCHAIN_NODE_TYPE)
+        if (!agentNode || agentNode.type !== AGENT_LANGCHAIN_NODE_TYPE)
             return undefined;
         const connectedTools = this.workflow
-            .getParentNodes(this.activeNodeName, interfaces_1.NodeConnectionTypes.AiTool)
+            .getParentNodes(this.activeNodeName, NodeConnectionTypes.AiTool)
             .map((nodeName) => this.workflow.getNode(nodeName))
             .filter((node) => node);
-        const memoryConnectedToAgent = this.workflow.getParentNodes(this.activeNodeName, interfaces_1.NodeConnectionTypes.AiMemory).length > 0;
+        const memoryConnectedToAgent = this.workflow.getParentNodes(this.activeNodeName, NodeConnectionTypes.AiMemory).length > 0;
         const allTools = this.workflow.queryNodes((nodeType) => {
             return nodeType.description.name.toLowerCase().includes('tool');
         });
         const unconnectedTools = allTools
-            .filter((node) => this.workflow.getChildNodes(node.name, interfaces_1.NodeConnectionTypes.AiTool, 1).length === 0)
+            .filter((node) => this.workflow.getChildNodes(node.name, NodeConnectionTypes.AiTool, 1).length === 0)
             .filter((node) => !connectedTools.includes(node));
         return {
             memoryConnectedToAgent,
@@ -189,9 +179,17 @@ class WorkflowDataProxy {
             ],
         };
     }
+    /**
+     * Returns a proxy which allows to query parameter data of a given node
+     *
+     * @private
+     * @param {string} nodeName The name of the node to query data from
+     * @param {boolean} [resolveValue=true] If the expression value should get resolved
+     */
     nodeParameterGetter(nodeName, resolveValue = true) {
         const that = this;
         const node = this.workflow.nodes[nodeName];
+        // `node` is `undefined` only in expressions in credentials
         return new Proxy(node?.parameters ?? {}, {
             has: () => true,
             ownKeys(target) {
@@ -207,13 +205,13 @@ class WorkflowDataProxy {
                 if (name === 'isProxy')
                     return true;
                 if (name === 'toJSON')
-                    return () => (0, utils_1.deepCopy)(target);
+                    return () => deepCopy(target);
                 name = name.toString();
                 let returnValue;
                 if (name[0] === '&') {
                     const key = name.slice(1);
                     if (!that.siblingParameters.hasOwnProperty(key)) {
-                        throw new application_error_1.ApplicationError('Could not find sibling parameter on node', {
+                        throw new ApplicationError('Could not find sibling parameter on node', {
                             extra: { nodeName, parameter: key },
                         });
                     }
@@ -221,13 +219,15 @@ class WorkflowDataProxy {
                 }
                 else {
                     if (!node.parameters.hasOwnProperty(name)) {
+                        // Parameter does not exist on node
                         return undefined;
                     }
                     returnValue = node.parameters[name];
                 }
+                // Avoid recursion
                 if (returnValue === `={{ $parameter.${name} }}`)
                     return undefined;
-                if ((0, type_guards_1.isResourceLocatorValue)(returnValue)) {
+                if (isResourceLocatorValue(returnValue)) {
                     if (returnValue.__regex && typeof returnValue.value === 'string') {
                         const expr = new RegExp(returnValue.__regex);
                         const extracted = expr.exec(returnValue.value);
@@ -243,6 +243,7 @@ class WorkflowDataProxy {
                     }
                 }
                 if (resolveValue && typeof returnValue === 'string' && returnValue.charAt(0) === '=') {
+                    // The found value is an expression so resolve it
                     return that.workflow.expression.getParameterValue(returnValue, that.runExecutionData, that.runIndex, that.itemIndex, that.activeNodeName, that.connectionInputData, that.mode, that.additionalKeys, that.executeData, false, {}, that.contextNodeName);
                 }
                 return returnValue;
@@ -254,25 +255,35 @@ class WorkflowDataProxy {
             return this.getNodeExecutionData(nodeName, shortSyntax, branchIndex, runIndex);
         }
         catch (e) {
-            const pinData = (0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(this.workflow, nodeName, this.mode);
+            const pinData = getPinDataIfManualExecution(this.workflow, nodeName, this.mode);
             if (pinData) {
                 return pinData;
             }
             throw e;
         }
     }
+    /**
+     * Returns the node ExecutionData
+     *
+     * @private
+     * @param {string} nodeName The name of the node query data from
+     * @param {boolean} [shortSyntax=false] If short syntax got used
+     * @param {number} [outputIndex] The index of the output, if not given the first one gets used
+     * @param {number} [runIndex] The index of the run, if not given the current one does get used
+     */
     getNodeExecutionData(nodeName, shortSyntax = false, outputIndex, runIndex) {
         const that = this;
         let executionData;
         if (!shortSyntax) {
+            // Long syntax got used to return data from node in path
             if (that.runExecutionData === null) {
-                throw new expression_error_1.ExpressionError("The workflow hasn't been executed yet, so you can't reference any output data", {
+                throw new ExpressionError("The workflow hasn't been executed yet, so you can't reference any output data", {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                 });
             }
             if (!that.workflow.getNode(nodeName)) {
-                throw new expression_error_1.ExpressionError("Referenced node doesn't exist", {
+                throw new ExpressionError("Referenced node doesn't exist", {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                     nodeCause: nodeName,
@@ -280,8 +291,8 @@ class WorkflowDataProxy {
                 });
             }
             if (!that.runExecutionData.resultData.runData.hasOwnProperty(nodeName) &&
-                !(0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, nodeName, that.mode)) {
-                throw new expression_error_1.ExpressionError('Referenced node is unexecuted', {
+                !getPinDataIfManualExecution(that.workflow, nodeName, that.mode)) {
+                throw new ExpressionError('Referenced node is unexecuted', {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                     type: 'no_node_execution_data',
@@ -293,22 +304,26 @@ class WorkflowDataProxy {
             runIndex =
                 runIndex === -1 ? that.runExecutionData.resultData.runData[nodeName].length - 1 : runIndex;
             if (that.runExecutionData.resultData.runData[nodeName].length <= runIndex) {
-                throw new expression_error_1.ExpressionError(`Run ${runIndex} of node "${nodeName}" not found`, {
+                throw new ExpressionError(`Run ${runIndex} of node "${nodeName}" not found`, {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                 });
             }
             const taskData = that.runExecutionData.resultData.runData[nodeName][runIndex].data;
             if (!taskData.main?.length || taskData.main[0] === null) {
-                throw new expression_error_1.ExpressionError('No data found from `main` input', {
+                // throw new ApplicationError('No data found for item-index', { extra: { itemIndex } });
+                throw new ExpressionError('No data found from `main` input', {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                 });
             }
+            // Check from which output to read the data.
+            // Depends on how the nodes are connected.
+            // (example "IF" node. If node is connected to "true" or to "false" output)
             if (outputIndex === undefined) {
-                const nodeConnection = that.workflow.getNodeConnectionIndexes(that.contextNodeName, nodeName, interfaces_1.NodeConnectionTypes.Main);
+                const nodeConnection = that.workflow.getNodeConnectionIndexes(that.contextNodeName, nodeName, NodeConnectionTypes.Main);
                 if (nodeConnection === undefined) {
-                    throw new expression_error_1.ExpressionError(`connect "${that.contextNodeName}" to "${nodeName}"`, {
+                    throw new ExpressionError(`connect "${that.contextNodeName}" to "${nodeName}"`, {
                         runIndex: that.runIndex,
                         itemIndex: that.itemIndex,
                     });
@@ -319,7 +334,7 @@ class WorkflowDataProxy {
                 outputIndex = 0;
             }
             if (taskData.main.length <= outputIndex) {
-                throw new expression_error_1.ExpressionError(`Node "${nodeName}" has no branch with index ${outputIndex}.`, {
+                throw new ExpressionError(`Node "${nodeName}" has no branch with index ${outputIndex}.`, {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                 });
@@ -327,10 +342,19 @@ class WorkflowDataProxy {
             executionData = taskData.main[outputIndex];
         }
         else {
+            // Short syntax got used to return data from active node
             executionData = that.connectionInputData;
         }
         return executionData;
     }
+    /**
+     * Returns a proxy which allows to query data of a given node
+     *
+     * @private
+     * @param {string} nodeName The name of the node query data from
+     * @param {boolean} [shortSyntax=false] If short syntax got used
+     * @param {boolean} [throwOnMissingExecutionData=true] If an error should get thrown if no execution data is available
+     */
     nodeDataGetter(nodeName, shortSyntax = false, throwOnMissingExecutionData = true) {
         const that = this;
         const node = this.workflow.nodes[nodeName];
@@ -341,7 +365,7 @@ class WorkflowDataProxy {
                     return true;
                 name = name.toString();
                 if (!node) {
-                    throw new expression_error_1.ExpressionError("Referenced node doesn't exist", {
+                    throw new ExpressionError("Referenced node doesn't exist", {
                         runIndex: that.runIndex,
                         itemIndex: that.itemIndex,
                         nodeCause: nodeName,
@@ -358,7 +382,7 @@ class WorkflowDataProxy {
                     }
                     if (executionData.length === 0) {
                         if (that.workflow.getParentNodes(nodeName).length === 0) {
-                            throw new expression_error_1.ExpressionError('No execution data available', {
+                            throw new ExpressionError('No execution data available', {
                                 messageTemplate: 'No execution data available to expression under ‘%%PARAMETER%%’',
                                 descriptionKey: 'noInputConnection',
                                 nodeCause: nodeName,
@@ -367,22 +391,24 @@ class WorkflowDataProxy {
                                 type: 'no_input_connection',
                             });
                         }
-                        throw new expression_error_1.ExpressionError('No execution data available', {
+                        throw new ExpressionError('No execution data available', {
                             runIndex: that.runIndex,
                             itemIndex: that.itemIndex,
                             type: 'no_execution_data',
                         });
                     }
                     if (executionData.length <= that.itemIndex) {
-                        throw new expression_error_1.ExpressionError(`No data found for item-index: "${that.itemIndex}"`, {
+                        throw new ExpressionError(`No data found for item-index: "${that.itemIndex}"`, {
                             runIndex: that.runIndex,
                             itemIndex: that.itemIndex,
                         });
                     }
                     if (['data', 'json'].includes(name)) {
+                        // JSON-Data
                         return executionData[that.itemIndex].json;
                     }
                     if (name === 'binary') {
+                        // Binary-Data
                         const returnData = {};
                         if (!executionData[that.itemIndex].binary) {
                             return returnData;
@@ -393,6 +419,7 @@ class WorkflowDataProxy {
                             const binaryData = binaryKeyData[keyName];
                             for (const propertyName in binaryData) {
                                 if (propertyName === 'data') {
+                                    // Skip the data property
                                     continue;
                                 }
                                 returnData[keyName][propertyName] = binaryData[propertyName];
@@ -405,6 +432,7 @@ class WorkflowDataProxy {
                     return that.nodeContextGetter(nodeName);
                 }
                 else if (name === 'parameter') {
+                    // Get node parameter data
                     return that.nodeParameterGetter(nodeName);
                 }
                 else if (name === 'runIndex') {
@@ -435,6 +463,7 @@ class WorkflowDataProxy {
                 if (name === 'isProxy')
                     return true;
                 if (!that.executeData?.source) {
+                    // Means the previous node did not get executed yet
                     return undefined;
                 }
                 const sourceData = that.executeData.source.main[0];
@@ -451,6 +480,11 @@ class WorkflowDataProxy {
             },
         });
     }
+    /**
+     * Returns a proxy to query data from the workflow
+     *
+     * @private
+     */
     workflowGetter() {
         const allowedValues = ['active', 'id', 'name'];
         const that = this;
@@ -471,7 +505,7 @@ class WorkflowDataProxy {
                 if (allowedValues.includes(name.toString())) {
                     const value = that.workflow[name];
                     if (value === undefined && name === 'id') {
-                        throw new expression_error_1.ExpressionError('save workflow to view', {
+                        throw new ExpressionError('save workflow to view', {
                             description: 'Please save the workflow first to use $workflow',
                             runIndex: that.runIndex,
                             itemIndex: that.itemIndex,
@@ -483,6 +517,11 @@ class WorkflowDataProxy {
             },
         });
     }
+    /**
+     * Returns a proxy to query data of all nodes
+     *
+     * @private
+     */
     nodeGetter() {
         const that = this;
         return new Proxy({}, {
@@ -492,7 +531,7 @@ class WorkflowDataProxy {
                     return true;
                 const nodeName = name.toString();
                 if (that.workflow.getNode(nodeName) === null) {
-                    throw new expression_error_1.ExpressionError("Referenced node doesn't exist", {
+                    throw new ExpressionError("Referenced node doesn't exist", {
                         runIndex: that.runIndex,
                         itemIndex: that.itemIndex,
                         nodeCause: nodeName,
@@ -503,11 +542,16 @@ class WorkflowDataProxy {
             },
         });
     }
+    /**
+     * Returns the data proxy object which allows to query data from current run
+     *
+     */
     getDataProxy(opts) {
         const that = this;
+        // replacing proxies with the actual data.
         const jmespathWrapper = (data, query) => {
             if (typeof data !== 'object' || typeof query !== 'string') {
-                throw new expression_error_1.ExpressionError('expected two arguments (Object, string) for this function', {
+                throw new ExpressionError('expected two arguments (Object, string) for this function', {
                     runIndex: that.runIndex,
                     itemIndex: that.itemIndex,
                 });
@@ -519,13 +563,17 @@ class WorkflowDataProxy {
         };
         const createExpressionError = (message, context) => {
             if (isScriptingNode(that.activeNodeName, that.workflow) && context?.functionOverrides) {
+                // If the node in which the error is thrown is a function node,
+                // display a different error message in case there is one defined
                 message = context.functionOverrides.message || message;
                 context.description = context.functionOverrides.description || context.description;
+                // The error will be in the code and not on an expression on a parameter
+                // so remove the messageTemplate as it would overwrite the message
                 context.messageTemplate = undefined;
             }
             if (context?.nodeCause) {
                 const nodeName = context.nodeCause;
-                const pinData = (0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, nodeName, that.mode);
+                const pinData = getPinDataIfManualExecution(that.workflow, nodeName, that.mode);
                 if (pinData) {
                     if (!context) {
                         context = {};
@@ -541,7 +589,7 @@ class WorkflowDataProxy {
                         context.descriptionTemplate += moreInfoLink;
                 }
             }
-            return new expression_error_1.ExpressionError(message, {
+            return new ExpressionError(message, {
                 runIndex: that.runIndex,
                 itemIndex: that.itemIndex,
                 ...context,
@@ -560,11 +608,11 @@ class WorkflowDataProxy {
             });
         };
         const createMissingPairedItemError = (nodeCause, usedMethodName = PAIRED_ITEM_METHOD.PAIRED_ITEM) => {
-            const pinData = (0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, nodeCause, that.mode);
+            const pinData = getPinDataIfManualExecution(that.workflow, nodeCause, that.mode);
             const message = pinData
                 ? `Using the ${usedMethodName} method doesn't work with pinned data in this scenario. Please unpin '${nodeCause}' and try again.`
                 : `Paired item data for ${usedMethodName} from node '${nodeCause}' is unavailable. Ensure '${nodeCause}' is providing the required output.`;
-            return new expression_error_1.ExpressionError(message, {
+            return new ExpressionError(message, {
                 runIndex: that.runIndex,
                 itemIndex: that.itemIndex,
                 functionality: 'pairedItem',
@@ -641,7 +689,7 @@ class WorkflowDataProxy {
         }
         function getTaskData(source) {
             return (that.runExecutionData?.resultData?.runData?.[source.previousNode]?.[source.previousNodeRun || 0] ??
-                pinDataToTask((0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, source.previousNode, that.mode)));
+                pinDataToTask(getPinDataIfManualExecution(that.workflow, source.previousNode, that.mode)));
         }
         function getNodeOutput(taskData, source, nodeCause) {
             const outputIndex = source.previousNodeOutput || 0;
@@ -665,6 +713,7 @@ class WorkflowDataProxy {
             return pairedItems.map((p) => (typeof p === 'number' ? { item: p } : p));
         };
         const getPairedItem = (destinationNodeName, incomingSourceData, initialPairedItem, usedMethodName = PAIRED_ITEM_METHOD.$GET_PAIRED_ITEM, nodeBeforeLast) => {
+            // Normalize inputs
             const [pairedItem, sourceData] = normalizeInputs(initialPairedItem, incomingSourceData);
             if (!sourceData) {
                 throw createPairedItemNotFound(destinationNodeName, nodeBeforeLast);
@@ -673,26 +722,29 @@ class WorkflowDataProxy {
             const outputData = getNodeOutput(taskData, sourceData, nodeBeforeLast);
             const item = outputData[pairedItem.item];
             const sourceArray = taskData?.source ?? [];
+            // Done: reached the destination node in the ancestry chain
             if (sourceData.previousNode === destinationNodeName) {
                 if (pairedItem.item >= outputData.length) {
                     throw createInvalidPairedItemError({ nodeName: sourceData.previousNode });
                 }
                 return item;
             }
+            // Normalize paired item to always be IPairedItemData[]
             const nextPairedItems = normalizePairedItem(item.pairedItem);
             if (nextPairedItems.length === 0) {
                 throw createMissingPairedItemError(sourceData.previousNode, usedMethodName);
             }
+            // Recursively traverse ancestry to find the destination node + paired item
             const results = nextPairedItems.flatMap((nextPairedItem) => {
                 const inputIndex = nextPairedItem.input ?? 0;
                 if (inputIndex >= sourceArray.length)
                     return [];
                 const nextSource = nextPairedItem.sourceOverwrite ?? sourceArray[inputIndex];
                 try {
-                    return (0, result_1.createResultOk)(getPairedItem(destinationNodeName, nextSource, { ...nextPairedItem, input: inputIndex }, usedMethodName, sourceData.previousNode));
+                    return createResultOk(getPairedItem(destinationNodeName, nextSource, { ...nextPairedItem, input: inputIndex }, usedMethodName, sourceData.previousNode));
                 }
                 catch (error) {
-                    return (0, result_1.createResultError)(error);
+                    return createResultError(error);
                 }
             });
             if (results.every((result) => !result.ok)) {
@@ -713,28 +765,30 @@ class WorkflowDataProxy {
         const handleFromAi = (name, _description, _type = 'string', defaultValue) => {
             const { itemIndex, runIndex } = that;
             if (!name || name === '') {
-                throw new expression_error_1.ExpressionError("Add a key, e.g. $fromAI('placeholder_name')", {
+                throw new ExpressionError("Add a key, e.g. $fromAI('placeholder_name')", {
                     runIndex,
                     itemIndex,
                 });
             }
             const nameValidationRegex = /^[a-zA-Z0-9_-]{0,64}$/;
             if (!nameValidationRegex.test(name)) {
-                throw new expression_error_1.ExpressionError('Invalid parameter key, must be between 1 and 64 characters long and only contain lowercase letters, uppercase letters, numbers, underscores, and hyphens', {
+                throw new ExpressionError('Invalid parameter key, must be between 1 and 64 characters long and only contain lowercase letters, uppercase letters, numbers, underscores, and hyphens', {
                     runIndex,
                     itemIndex,
                 });
             }
             const inputData = that.runExecutionData?.resultData.runData[that.activeNodeName]?.[runIndex].inputOverride;
-            const placeholdersDataInputData = inputData?.[interfaces_1.NodeConnectionTypes.AiTool]?.[0]?.[itemIndex].json;
+            const placeholdersDataInputData = inputData?.[NodeConnectionTypes.AiTool]?.[0]?.[itemIndex].json;
             if (Boolean(!placeholdersDataInputData)) {
-                throw new expression_error_1.ExpressionError('No execution data available', {
+                throw new ExpressionError('No execution data available', {
                     runIndex,
                     itemIndex,
                     type: 'no_execution_data',
                 });
             }
-            return (placeholdersDataInputData?.query?.[name] ??
+            return (
+            // TS does not know that the key exists, we need to address this in refactor
+            placeholdersDataInputData?.query?.[name] ??
                 placeholdersDataInputData?.[name] ??
                 defaultValue);
         };
@@ -754,7 +808,7 @@ class WorkflowDataProxy {
                 }
                 const ensureNodeExecutionData = () => {
                     if (!that?.runExecutionData?.resultData?.runData.hasOwnProperty(nodeName) &&
-                        !(0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, nodeName, that.mode)) {
+                        !getPinDataIfManualExecution(that.workflow, nodeName, that.mode)) {
                         throw createExpressionError('Referenced node is unexecuted', {
                             runIndex: that.runIndex,
                             itemIndex: that.itemIndex,
@@ -788,6 +842,8 @@ class WorkflowDataProxy {
                         if (property === PAIRED_ITEM_METHOD.PAIRED_ITEM ||
                             property === PAIRED_ITEM_METHOD.ITEM_MATCHING ||
                             property === PAIRED_ITEM_METHOD.ITEM) {
+                            // Before resolving the pairedItem make sure that the requested node comes in the
+                            // graph before the current one
                             const activeNode = that.workflow.getNode(that.activeNodeName);
                             let contextNode = that.contextNodeName;
                             if (activeNode) {
@@ -809,7 +865,7 @@ class WorkflowDataProxy {
                                     itemIndex = that.itemIndex;
                                 }
                                 if (!that.connectionInputData.length) {
-                                    const pinnedData = (0, workflow_data_proxy_helpers_1.getPinDataIfManualExecution)(that.workflow, nodeName, that.mode);
+                                    const pinnedData = getPinDataIfManualExecution(that.workflow, nodeName, that.mode);
                                     if (pinnedData) {
                                         return pinnedData[itemIndex];
                                     }
@@ -830,6 +886,9 @@ class WorkflowDataProxy {
                                         type: 'paired_item_intermediate_nodes',
                                     });
                                 }
+                                // As we operate on the incoming item we can be sure that pairedItem is not an
+                                // array. After all can it only come from exactly one previous node via a certain
+                                // input. For that reason do we not have to consider the array case.
                                 const pairedItem = input.pairedItem;
                                 if (pairedItem === undefined) {
                                     throw createMissingPairedItemError(that.activeNodeName, property);
@@ -860,6 +919,7 @@ class WorkflowDataProxy {
                             return (branchIndex, runIndex) => {
                                 branchIndex =
                                     branchIndex ??
+                                        // default to the output the active node is connected to
                                         that.workflow.getNodeConnectionIndexes(that.activeNodeName, nodeName)
                                             ?.sourceIndex ??
                                         0;
@@ -878,6 +938,7 @@ class WorkflowDataProxy {
                             return (branchIndex, runIndex) => {
                                 branchIndex =
                                     branchIndex ??
+                                        // default to the output the active node is connected to
                                         that.workflow.getNodeConnectionIndexes(that.activeNodeName, nodeName)
                                             ?.sourceIndex ??
                                         0;
@@ -899,6 +960,7 @@ class WorkflowDataProxy {
                             return (branchIndex, runIndex) => {
                                 branchIndex =
                                     branchIndex ??
+                                        // default to the output the active node is connected to
                                         that.workflow.getNodeConnectionIndexes(that.activeNodeName, nodeName)
                                             ?.sourceIndex ??
                                         0;
@@ -973,6 +1035,8 @@ class WorkflowDataProxy {
                         };
                     }
                     if (['context', 'params'].includes(property)) {
+                        // For the following properties we need the source data so fail in case it is missing
+                        // for some reason (even though that should actually never happen)
                         if (!that.executeData?.source) {
                             throw createExpressionError('Can’t get data for expression', {
                                 messageTemplate: 'Can’t get data for expression under ‘%%PARAMETER%%’ field',
@@ -995,9 +1059,9 @@ class WorkflowDataProxy {
                     return Reflect.get(target, property, receiver);
                 },
             }),
-            $binary: {},
-            $data: {},
-            $env: (0, workflow_data_proxy_env_provider_1.createEnvProvider)(that.runIndex, that.itemIndex, that.envProviderState ?? (0, workflow_data_proxy_env_provider_1.createEnvProviderState)()),
+            $binary: {}, // Placeholder
+            $data: {}, // Placeholder
+            $env: createEnvProvider(that.runIndex, that.itemIndex, that.envProviderState ?? createEnvProviderState()),
             $evaluateExpression: (expression, itemIndex) => {
                 itemIndex = itemIndex || that.itemIndex;
                 return that.workflow.expression.getParameterValue(`=${expression}`, that.runExecutionData, that.runIndex, itemIndex, that.activeNodeName, that.connectionInputData, that.mode, that.additionalKeys, that.executeData, false, {}, that.contextNodeName);
@@ -1008,6 +1072,7 @@ class WorkflowDataProxy {
                 return dataProxy.getDataProxy();
             },
             $fromAI: handleFromAi,
+            // Make sure mis-capitalized $fromAI is handled correctly even though we don't auto-complete it
             $fromai: handleFromAi,
             $fromAi: handleFromAi,
             $items: (nodeName, outputIndex, runIndex) => {
@@ -1027,7 +1092,7 @@ class WorkflowDataProxy {
                 runIndex = runIndex === undefined ? -1 : runIndex;
                 return that.getNodeExecutionData(nodeName, false, outputIndex, runIndex);
             },
-            $json: {},
+            $json: {}, // Placeholder
             $node: this.nodeGetter(),
             $self: this.selfGetter(),
             $parameter: this.nodeParameterGetter(this.activeNodeName),
@@ -1037,14 +1102,15 @@ class WorkflowDataProxy {
             $mode: this.mode,
             $workflow: this.workflowGetter(),
             $itemIndex: this.itemIndex,
-            $now: luxon_1.DateTime.now(),
-            $today: luxon_1.DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }),
+            $now: DateTime.now(),
+            $today: DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }),
             $jmesPath: jmespathWrapper,
-            DateTime: luxon_1.DateTime,
-            Interval: luxon_1.Interval,
-            Duration: luxon_1.Duration,
+            DateTime,
+            Interval,
+            Duration,
             ...that.additionalKeys,
             $getPairedItem: getPairedItem,
+            // deprecated
             $jmespath: jmespathWrapper,
             $position: this.itemIndex,
             $thisItem: that.connectionInputData[that.itemIndex],
@@ -1073,5 +1139,4 @@ class WorkflowDataProxy {
         });
     }
 }
-exports.WorkflowDataProxy = WorkflowDataProxy;
 //# sourceMappingURL=workflow-data-proxy.js.map