feat: Add once for each item support for JS task runner (no-changelog) (#11109)

packages/nodes-base/nodes/Code/Code.node.ts

@@ -1,3 +1,5 @@
+import { TaskRunnersConfig } from '@n8n/config';
+import set from 'lodash/set';
 import {
 	NodeConnectionType,
 	type CodeExecutionMode,
@@ -7,13 +9,12 @@ import {
 	type INodeType,
 	type INodeTypeDescription,
 } from 'n8n-workflow';
-import set from 'lodash/set';
 import Container from 'typedi';
-import { TaskRunnersConfig } from '@n8n/config';
 
 import { javascriptCodeDescription } from './descriptions/JavascriptCodeDescription';
 import { pythonCodeDescription } from './descriptions/PythonCodeDescription';
 import { JavaScriptSandbox } from './JavaScriptSandbox';
+import { JsTaskRunnerSandbox } from './JsTaskRunnerSandbox';
 import { PythonSandbox } from './PythonSandbox';
 import { getSandboxContext } from './Sandbox';
 import { standardizeOutput } from './utils';
@@ -108,23 +109,17 @@ export class Code implements INodeType {
 		const codeParameterName = language === 'python' ? 'pythonCode' : 'jsCode';
 
 		if (!runnersConfig.disabled && language === 'javaScript') {
-			// TODO: once per item
 			const code = this.getNodeParameter(codeParameterName, 0) as string;
-			const items = await this.startJob<INodeExecutionData[]>(
-				{ javaScript: 'javascript', python: 'python' }[language] ?? language,
-				{
-					code,
-					nodeMode,
-					workflowMode,
-				},
-				0,
-			);
+			const sandbox = new JsTaskRunnerSandbox(code, nodeMode, workflowMode, this);
 
-			return [items];
+			return nodeMode === 'runOnceForAllItems'
+				? [await sandbox.runCodeAllItems()]
+				: [await sandbox.runCodeForEachItem()];
 		}
 
 		const getSandbox = (index = 0) => {
 			const code = this.getNodeParameter(codeParameterName, index) as string;
+
 			const context = getSandboxContext.call(this, index);
 			if (nodeMode === 'runOnceForAllItems') {
 				context.items = context.$input.all();
@@ -133,7 +128,7 @@ export class Code implements INodeType {
 			}
 
 			const Sandbox = language === 'python' ? PythonSandbox : JavaScriptSandbox;
-			const sandbox = new Sandbox(context, code, index, this.helpers);
+			const sandbox = new Sandbox(context, code, this.helpers);
 			sandbox.on(
 				'output',
 				workflowMode === 'manual'
@@ -182,7 +177,7 @@ export class Code implements INodeType {
 			const sandbox = getSandbox(index);
 			let result: INodeExecutionData | undefined;
 			try {
-				result = await sandbox.runCodeEachItem();
+				result = await sandbox.runCodeEachItem(index);
 			} catch (error) {
 				if (!this.continueOnFail()) {
 					set(error, 'node', node);

packages/nodes-base/nodes/Code/ExecutionError.ts

@@ -11,7 +11,7 @@ export class ExecutionError extends ApplicationError {
 
 	lineNumber: number | undefined = undefined;
 
-	constructor(error: Error & { stack: string }, itemIndex?: number) {
+	constructor(error: Error & { stack?: string }, itemIndex?: number) {
 		super(error.message);
 		this.itemIndex = itemIndex;
 
@@ -19,7 +19,7 @@ export class ExecutionError extends ApplicationError {
 			this.context = { itemIndex: this.itemIndex };
 		}
 
-		this.stack = error.stack;
+		this.stack = error.stack ?? '';
 
 		this.populateFromStack();
 	}

packages/nodes-base/nodes/Code/JavaScriptSandbox.ts

@@ -5,6 +5,11 @@ import { ValidationError } from './ValidationError';
 import { ExecutionError } from './ExecutionError';
 import type { SandboxContext } from './Sandbox';
 import { Sandbox } from './Sandbox';
+import {
+	mapItemNotDefinedErrorIfNeededForRunForEach,
+	mapItemsNotDefinedErrorIfNeededForRunForAll,
+	validateNoDisallowedMethodsInRunForEach,
+} from './JsCodeValidator';
 
 const { NODE_FUNCTION_ALLOW_BUILTIN: builtIn, NODE_FUNCTION_ALLOW_EXTERNAL: external } =
 	process.env;
@@ -25,7 +30,6 @@ export class JavaScriptSandbox extends Sandbox {
 	constructor(
 		context: SandboxContext,
 		private jsCode: string,
-		itemIndex: number | undefined,
 		helpers: IExecuteFunctions['helpers'],
 		options?: { resolver?: Resolver },
 	) {
@@ -36,7 +40,6 @@ export class JavaScriptSandbox extends Sandbox {
 					plural: 'objects',
 				},
 			},
-			itemIndex,
 			helpers,
 		);
 		this.vm = new NodeVM({
@@ -49,10 +52,10 @@ export class JavaScriptSandbox extends Sandbox {
 		this.vm.on('console.log', (...args: unknown[]) => this.emit('output', ...args));
 	}
 
-	async runCode(): Promise<unknown> {
+	async runCode<T = unknown>(): Promise<T> {
 		const script = `module.exports = async function() {${this.jsCode}\n}()`;
 		try {
-			const executionResult = await this.vm.run(script, __dirname);
+			const executionResult = (await this.vm.run(script, __dirname)) as T;
 			return executionResult;
 		} catch (error) {
 			throw new ExecutionError(error);
@@ -70,10 +73,7 @@ export class JavaScriptSandbox extends Sandbox {
 			executionResult = await this.vm.run(script, __dirname);
 		} catch (error) {
 			// anticipate user expecting `items` to pre-exist as in Function Item node
-			if (error.message === 'items is not defined' && !/(let|const|var) items =/.test(script)) {
-				const quoted = error.message.replace('items', '`items`');
-				error.message = (quoted as string) + '. Did you mean `$input.all()`?';
-			}
+			mapItemsNotDefinedErrorIfNeededForRunForAll(this.jsCode, error);
 
 			throw new ExecutionError(error);
 		}
@@ -87,7 +87,6 @@ export class JavaScriptSandbox extends Sandbox {
 					message: "The code doesn't return an array of arrays",
 					description:
 						'Please return an array of arrays. One array for the different outputs and one for the different items that get returned.',
-					itemIndex: this.itemIndex,
 				});
 			}
 
@@ -101,30 +100,10 @@ export class JavaScriptSandbox extends Sandbox {
 		);
 	}
 
-	async runCodeEachItem(): Promise<INodeExecutionData | undefined> {
+	async runCodeEachItem(itemIndex: number): Promise<INodeExecutionData | undefined> {
 		const script = `module.exports = async function() {${this.jsCode}\n}()`;
 
-		const match = this.jsCode.match(/\$input\.(?<disallowedMethod>first|last|all|itemMatching)/);
-
-		if (match?.groups?.disallowedMethod) {
-			const { disallowedMethod } = match.groups;
-
-			const lineNumber =
-				this.jsCode.split('\n').findIndex((line) => {
-					return line.includes(disallowedMethod) && !line.startsWith('//') && !line.startsWith('*');
-				}) + 1;
-
-			const disallowedMethodFound = lineNumber !== 0;
-
-			if (disallowedMethodFound) {
-				throw new ValidationError({
-					message: `Can't use .${disallowedMethod}() here`,
-					description: "This is only available in 'Run Once for All Items' mode",
-					itemIndex: this.itemIndex,
-					lineNumber,
-				});
-			}
-		}
+		validateNoDisallowedMethodsInRunForEach(this.jsCode, itemIndex);
 
 		let executionResult: INodeExecutionData;
 
@@ -132,16 +111,13 @@ export class JavaScriptSandbox extends Sandbox {
 			executionResult = await this.vm.run(script, __dirname);
 		} catch (error) {
 			// anticipate user expecting `item` to pre-exist as in Function Item node
-			if (error.message === 'item is not defined' && !/(let|const|var) item =/.test(script)) {
-				const quoted = error.message.replace('item', '`item`');
-				error.message = (quoted as string) + '. Did you mean `$input.item.json`?';
-			}
+			mapItemNotDefinedErrorIfNeededForRunForEach(this.jsCode, error);
 
-			throw new ExecutionError(error, this.itemIndex);
+			throw new ExecutionError(error, itemIndex);
 		}
 
-		if (executionResult === null) return;
+		if (executionResult === null) return undefined;
 
-		return this.validateRunCodeEachItem(executionResult);
+		return this.validateRunCodeEachItem(executionResult, itemIndex);
 	}
 }

packages/nodes-base/nodes/Code/JsCodeValidator.ts

@@ -0,0 +1,54 @@
+import { ValidationError } from './ValidationError';
+
+/**
+ * Validates that no disallowed methods are used in the
+ * runCodeForEachItem JS code. Throws `ValidationError` if
+ * a disallowed method is found.
+ */
+export function validateNoDisallowedMethodsInRunForEach(code: string, itemIndex: number) {
+	const match = code.match(/\$input\.(?<disallowedMethod>first|last|all|itemMatching)/);
+
+	if (match?.groups?.disallowedMethod) {
+		const { disallowedMethod } = match.groups;
+
+		const lineNumber =
+			code.split('\n').findIndex((line) => {
+				return line.includes(disallowedMethod) && !line.startsWith('//') && !line.startsWith('*');
+			}) + 1;
+
+		const disallowedMethodFound = lineNumber !== 0;
+
+		if (disallowedMethodFound) {
+			throw new ValidationError({
+				message: `Can't use .${disallowedMethod}() here`,
+				description: "This is only available in 'Run Once for All Items' mode",
+				itemIndex,
+				lineNumber,
+			});
+		}
+	}
+}
+
+/**
+ * Checks if the error message indicates that `items` is not defined and
+ * modifies the error message to suggest using `$input.all()`.
+ */
+export function mapItemsNotDefinedErrorIfNeededForRunForAll(code: string, error: Error) {
+	// anticipate user expecting `items` to pre-exist as in Function Item node
+	if (error.message === 'items is not defined' && !/(let|const|var) +items +=/.test(code)) {
+		const quoted = error.message.replace('items', '`items`');
+		error.message = (quoted as string) + '. Did you mean `$input.all()`?';
+	}
+}
+
+/**
+ * Maps the "item is not defined" error message to provide a more helpful suggestion
+ * for users who may expect `items` to pre-exist
+ */
+export function mapItemNotDefinedErrorIfNeededForRunForEach(code: string, error: Error) {
+	// anticipate user expecting `items` to pre-exist as in Function Item node
+	if (error.message === 'item is not defined' && !/(let|const|var) +item +=/.test(code)) {
+		const quoted = error.message.replace('item', '`item`');
+		error.message = (quoted as string) + '. Did you mean `$input.item.json`?';
+	}
+}

packages/nodes-base/nodes/Code/JsTaskRunnerSandbox.ts

@@ -0,0 +1,92 @@
+import {
+	ensureError,
+	type CodeExecutionMode,
+	type IExecuteFunctions,
+	type INodeExecutionData,
+	type WorkflowExecuteMode,
+} from 'n8n-workflow';
+
+import { ExecutionError } from './ExecutionError';
+import {
+	mapItemsNotDefinedErrorIfNeededForRunForAll,
+	validateNoDisallowedMethodsInRunForEach,
+} from './JsCodeValidator';
+
+/**
+ * JS Code execution sandbox that executes the JS code using task runner.
+ */
+export class JsTaskRunnerSandbox {
+	constructor(
+		private readonly jsCode: string,
+		private readonly nodeMode: CodeExecutionMode,
+		private readonly workflowMode: WorkflowExecuteMode,
+		private readonly executeFunctions: IExecuteFunctions,
+	) {}
+
+	async runCode<T = unknown>(): Promise<T> {
+		const itemIndex = 0;
+
+		try {
+			const executionResult = (await this.executeFunctions.startJob<T>(
+				'javascript',
+				{
+					code: this.jsCode,
+					nodeMode: this.nodeMode,
+					workflowMode: this.workflowMode,
+				},
+				itemIndex,
+			)) as T;
+			return executionResult;
+		} catch (e) {
+			const error = ensureError(e);
+			throw new ExecutionError(error);
+		}
+	}
+
+	async runCodeAllItems(): Promise<INodeExecutionData[]> {
+		const itemIndex = 0;
+
+		return await this.executeFunctions
+			.startJob<INodeExecutionData[]>(
+				'javascript',
+				{
+					code: this.jsCode,
+					nodeMode: this.nodeMode,
+					workflowMode: this.workflowMode,
+					continueOnFail: this.executeFunctions.continueOnFail(),
+				},
+				itemIndex,
+			)
+			.catch((e) => {
+				const error = ensureError(e);
+				// anticipate user expecting `items` to pre-exist as in Function Item node
+				mapItemsNotDefinedErrorIfNeededForRunForAll(this.jsCode, error);
+
+				throw new ExecutionError(error);
+			});
+	}
+
+	async runCodeForEachItem(): Promise<INodeExecutionData[]> {
+		validateNoDisallowedMethodsInRunForEach(this.jsCode, 0);
+		const itemIndex = 0;
+
+		return await this.executeFunctions
+			.startJob<INodeExecutionData[]>(
+				'javascript',
+				{
+					code: this.jsCode,
+					nodeMode: this.nodeMode,
+					workflowMode: this.workflowMode,
+					continueOnFail: this.executeFunctions.continueOnFail(),
+				},
+				itemIndex,
+			)
+			.catch((e) => {
+				const error = ensureError(e);
+				// anticipate user expecting `items` to pre-exist as in Function Item node
+				mapItemsNotDefinedErrorIfNeededForRunForAll(this.jsCode, error);
+
+				throw new ExecutionError(error);
+			});
+	}
+}

packages/nodes-base/nodes/Code/PythonSandbox.ts

@@ -18,7 +18,6 @@ export class PythonSandbox extends Sandbox {
 	constructor(
 		context: SandboxContext,
 		private pythonCode: string,
-		itemIndex: number | undefined,
 		helpers: IExecuteFunctions['helpers'],
 	) {
 		super(
@@ -28,7 +27,6 @@ export class PythonSandbox extends Sandbox {
 					plural: 'dictionaries',
 				},
 			},
-			itemIndex,
 			helpers,
 		);
 		// Since python doesn't allow variable names starting with `$`,
@@ -39,8 +37,8 @@ export class PythonSandbox extends Sandbox {
 		}, {} as PythonSandboxContext);
 	}
 
-	async runCode(): Promise<unknown> {
-		return await this.runCodeInPython<unknown>();
+	async runCode<T = unknown>(): Promise<T> {
+		return await this.runCodeInPython<T>();
 	}
 
 	async runCodeAllItems() {
@@ -48,9 +46,9 @@ export class PythonSandbox extends Sandbox {
 		return this.validateRunCodeAllItems(executionResult);
 	}
 
-	async runCodeEachItem() {
+	async runCodeEachItem(itemIndex: number) {
 		const executionResult = await this.runCodeInPython<INodeExecutionData>();
-		return this.validateRunCodeEachItem(executionResult);
+		return this.validateRunCodeEachItem(executionResult, itemIndex);
 	}
 
 	private async runCodeInPython<T>() {

packages/nodes-base/nodes/Code/Sandbox.ts

@@ -1,7 +1,8 @@
 import { EventEmitter } from 'events';
 import type { IExecuteFunctions, INodeExecutionData, IWorkflowDataProxyData } from 'n8n-workflow';
-import { ValidationError } from './ValidationError';
+
 import { isObject } from './utils';
+import { ValidationError } from './ValidationError';
 
 interface SandboxTextKeys {
 	object: {
@@ -39,26 +40,28 @@ export function getSandboxContext(this: IExecuteFunctions, index: number): Sandb
 export abstract class Sandbox extends EventEmitter {
 	constructor(
 		private textKeys: SandboxTextKeys,
-		protected itemIndex: number | undefined,
 		protected helpers: IExecuteFunctions['helpers'],
 	) {
 		super();
 	}
 
-	abstract runCode(): Promise<unknown>;
+	abstract runCode<T = unknown>(): Promise<T>;
 
 	abstract runCodeAllItems(): Promise<INodeExecutionData[] | INodeExecutionData[][]>;
 
-	abstract runCodeEachItem(): Promise<INodeExecutionData | undefined>;
+	abstract runCodeEachItem(itemIndex: number): Promise<INodeExecutionData | undefined>;
 
-	validateRunCodeEachItem(executionResult: INodeExecutionData | undefined): INodeExecutionData {
+	validateRunCodeEachItem(
+		executionResult: INodeExecutionData | undefined,
+		itemIndex: number,
+	): INodeExecutionData {
 		if (typeof executionResult !== 'object') {
 			throw new ValidationError({
 				message: `Code doesn't return ${this.getTextKey('object', { includeArticle: true })}`,
 				description: `Please return ${this.getTextKey('object', {
 					includeArticle: true,
 				})} representing the output item. ('${executionResult}' was returned instead.)`,
-				itemIndex: this.itemIndex,
+				itemIndex,
 			});
 		}
 
@@ -70,25 +73,24 @@ export abstract class Sandbox extends EventEmitter {
 			throw new ValidationError({
 				message: `Code doesn't return a single ${this.getTextKey('object')}`,
 				description: `${firstSentence} If you need to output multiple items, please use the 'Run Once for All Items' mode instead.`,
-				itemIndex: this.itemIndex,
+				itemIndex,
 			});
 		}
 
 		const [returnData] = this.helpers.normalizeItems([executionResult]);
 
-		this.validateItem(returnData);
+		this.validateItem(returnData, itemIndex);
 
 		// If at least one top-level key is a supported item key (`json`, `binary`, etc.),
 		// and another top-level key is unrecognized, then the user mis-added a property
 		// directly on the item, when they intended to add it on the `json` property
-		this.validateTopLevelKeys(returnData);
+		this.validateTopLevelKeys(returnData, itemIndex);
 
 		return returnData;
 	}
 
 	validateRunCodeAllItems(
 		executionResult: INodeExecutionData | INodeExecutionData[] | undefined,
-		itemIndex?: number,
 	): INodeExecutionData[] {
 		if (typeof executionResult !== 'object') {
 			throw new ValidationError({
@@ -96,7 +98,6 @@ export abstract class Sandbox extends EventEmitter {
 				description: `Please return an array of ${this.getTextKey('object', {
 					plural: true,
 				})}, one for each item you would like to output.`,
-				itemIndex,
 			});
 		}
 
@@ -113,14 +114,15 @@ export abstract class Sandbox extends EventEmitter {
 			);
 
 			if (mustHaveTopLevelN8nKey) {
-				for (const item of executionResult) {
-					this.validateTopLevelKeys(item);
+				for (let index = 0; index < executionResult.length; index++) {
+					const item = executionResult[index];
+					this.validateTopLevelKeys(item, index);
 				}
 			}
 		}
 
 		const returnData = this.helpers.normalizeItems(executionResult);
-		returnData.forEach((item) => this.validateItem(item));
+		returnData.forEach((item, index) => this.validateItem(item, index));
 		return returnData;
 	}
 
@@ -138,7 +140,7 @@ export abstract class Sandbox extends EventEmitter {
 		return `a ${response}`;
 	}
 
-	private validateItem({ json, binary }: INodeExecutionData) {
+	private validateItem({ json, binary }: INodeExecutionData, itemIndex: number) {
 		if (json === undefined || !isObject(json)) {
 			throw new ValidationError({
 				message: `A 'json' property isn't ${this.getTextKey('object', { includeArticle: true })}`,
@@ -146,7 +148,7 @@ export abstract class Sandbox extends EventEmitter {
 					'object',
 					{ includeArticle: true },
 				)}.`,
-				itemIndex: this.itemIndex,
+				itemIndex,
 			});
 		}
 
@@ -157,18 +159,18 @@ export abstract class Sandbox extends EventEmitter {
 					'object',
 					{ includeArticle: true },
 				)}.`,
-				itemIndex: this.itemIndex,
+				itemIndex,
 			});
 		}
 	}
 
-	private validateTopLevelKeys(item: INodeExecutionData) {
+	private validateTopLevelKeys(item: INodeExecutionData, itemIndex: number) {
 		Object.keys(item).forEach((key) => {
 			if (REQUIRED_N8N_ITEM_KEYS.has(key)) return;
 			throw new ValidationError({
 				message: `Unknown top-level item key: ${key}`,
 				description: 'Access the properties of an item under `.json`, e.g. `item.json`',
-				itemIndex: this.itemIndex,
+				itemIndex,
 			});
 		});
 	}