JavaScript

The JavaScript operation allows users to write custom logic in JavaScript, leveraging the lightweight QuickJS-ng runtime. It supports dynamic scripting through an Init Script (executed once upon component creation) and a Run Script (executed every time the component is reached in an active execution path), enabling flexible data processing and flow control.

Inputs

Port	Type	Required	Description
In [1—20]	User-configurable	No	Flexible inputs that pass data into the JavaScript environment. Each value is accessible via getInput(inputNumber). Up to 20 connectable inputs. Accepted MessagePack types per port are set in the Node’s Settings panel — see Setting Port Types.

Outputs

Port	Type	Default	Description
Out [1—20]	User-configurable	Nil	Flexible outputs set from the script via setOutput(outputNumber, value). Up to 20 connectable outputs. Accepted MessagePack types per port are set in the Node’s Settings panel.

Properties

Name	Type	Default	Description
Init	TextBox (multi-line)	""	JavaScript code executed once when the component is created. Use var for variables shared with the Run script.
Run	TextBox (multi-line)	""	JavaScript code executed every time the component is reached in an active execution path.
On Error	Combo	Stop this branch	Per-op On Error verb (Stop this branch / Continue with the last value / Continue with the fallback). See the Error Handling guide.

State on Reload

State is preserved across restarts within the configured time window. The current outputs and the global state value (if present) are saved. State is restored only if the Init and Run scripts are unchanged (script hash match). The saved state is applied after the Init Script has run.

---

Utility Functions

The following global functions are available in both the Init and Run scripts:

Function	Description
getInput(inputNumber)	Returns the decoded native JavaScript value of the given 1-based input. Unconnected or invalid inputs return undefined; MessagePack Nil becomes null. Maps with only string keys become plain objects; others become Map.
setOutput(outputNumber, value)	Sets an output using a native JavaScript value. Array/Object/Map are converted recursively; Uint8Array/ArrayBuffer becomes binary; null, undefined, and unsupported types become Nil. BigInt is supported up to 64-bit range.
pathHalt(shouldHalt)	Controls whether the execution path stops after this operation. Pass true to stop, false (or omit the call) to continue. See Error Handling below.
console.log(...args)	Logs messages to the system Statuses table for debugging.

---

How It Works

1. Initialization — When the component is first created, deployed, or reloaded, the Init script is executed once. Variables declared with var or function are available in the Run script.

2. Runtime execution — Each time the component is reached in an active execution path, the Run script is processed.

3. Input handling — Within the Run script, getInput(inputNumber) returns decoded native JavaScript values from the MessagePack inputs.

4. Custom logic — The script processes values, performs calculations, applies conditional logic, or manipulates data as needed.

5. Output handling — Results are set using setOutput(outputNumber, value). Conversion to MessagePack is handled automatically.

6. Path control — pathHalt(true) can be called to stop the execution path based on conditions within the script. If not called or called with false, the path continues.

---

Examples

Data format

All inputs and outputs use MessagePack internally. The examples below show values in JSON notation for readability.

Pass-Through

Purpose: Pass data from a single input directly to a single output.

Run Script:

let input1 = getInput(1);
setOutput(1, input1);

Input 1: "Some data"

Output 1: "Some data"

Stateful Counter

Purpose: A counter stored in the global state object, preserved across reloads.

Init Script:

state = {count: 100};

Run Script:

state.count += 1;
setOutput(1, state.count);

• First run: Output 1 = 101
• Second run: Output 1 = 102
• After reload (same scripts): saved state.count is restored, next run continues from where it left off.

Conditional Stop

Purpose: Use a threshold from the Init script and conditionally stop the execution path.

Init Script:

var threshold = 100;

Run Script:

let input1 = getInput(1);
if (input1 > threshold) {
  setOutput(1, input1);
} else {
  pathHalt(true);
}

• Input 1 = 150: Output 1 = 150, path continues.
• Input 1 = 80: Output 1 unchanged, path stops.

Type Processing

Purpose: Process values differently based on type.

Run Script:

let input1 = getInput(1);
let result = input1;
if (typeof result === "number") {
  result += 1;
} else if (typeof result === "string") {
  result = result.toUpperCase();
}
setOutput(1, result);

• Input 1 = 5: Output 1 = 6
• Input 1 = "hello": Output 1 = "HELLO"

---

Notes

• The QuickJS-ng runtime is sandboxed. Browser APIs (DOM, setTimeout) and Node.js modules are not available.
• Execution is synchronous — avoid infinite loops or heavy computation that could block the workflow.
• Variables declared with let or const in the Init script are block-scoped and may not be accessible in the Run script. Use var for shared globals.
• Integers outside JavaScript’s safe range are represented as BigInt when read. BigInt values are accepted on output if they fit in 64-bit range.
• MessagePack Extension values are returned as undefined.
• If the Run script throws, the Node fails and its On Error verb resolves the branch; outputs the script already wrote are not cleared.

---

Error Handling

JavaScript carries an On Error verb like every other operation. What the script does is what decides which of the three answers a run gives:

What the script does	The run’s answer
Calls setOutput and returns	Produced. Every output the script set is written and stamped with this run, and the dependents run.
Calls pathHalt(true)	Stopped. The outputs are untouched and the dependents are skipped. This is a choice, not an error, so no verb is consulted.
Throws, and nothing catches it	Failed. The error is reported as JavaScript: run script failed, and the On Error verb below resolves the branch.

An uncaught throw is the script’s one way to say it could not produce. Outputs the script wrote before it threw keep the values and the stamps it gave them.

Verb	What a dependent gets
Stop this branch (default)	This Node and its dependents stop; every output keeps its value and reads as a failed update.
Continue with the last value	Dependents run on the value each output already holds, not stamped as new; it reads as a failed update.
Continue with the fallback	Dependents run on each output’s per-output Fallback, stamped as this run’s value; it reads as a failed update. The Editor refuses a Task where a Fallback is unset.

A Node that failed is also what a downstream Input configured with A value whose last update failed reads on its next fire, whichever verb the Node carries.

Wrap risky code in try/catch to decide for yourself which failures are worth failing the Node over.