JavaScript
Run a JavaScript function body in an embedded sandbox. No Node.js or other interpreter is needed on the host or on workers.
Basic Usage
steps:
- id: fetch
action: http.request
with:
method: GET
url: https://example.com
output: HTML
- id: links
depends: [fetch]
action: js.run
with:
input: ${HTML}
script: |
const urls = new Set();
for (const m of input.matchAll(/href="([^"]+)"/g)) {
urls.add(new URL(m[1], "https://example.com").href);
}
return [...urls];
output: LINKSOutput of links:
[
"https://example.com/a",
"https://example.com/b"
]When to Use
Use js.run to transform data between steps: parse, filter, reshape, extract with regular expressions, or compute values. It replaces inline python -c, Python or Node heredocs, and awk/sed/jq pipelines in run::
- No interpreter is needed on the host or on workers.
- The script is passed as written, so
${...}and$need no escaping. - Syntax errors fail
dagu validate, the editor, and MCP preview before a run starts. - The returned value is clean stdout, ready for
output:.
Keep run: for invoking CLIs and for work that needs the network, files, environment variables, or a library. A single path such as .items[].id is fine in jq.filter.
The Dagu agent skill and MCP authoring rules give coding agents the same guidance.
Configuration
| Field | Description |
|---|---|
script | JavaScript function body. Required. return a value to publish it. |
input | Any YAML value bound to input. Mutually exclusive with input_file. |
input_file | Path of a file whose contents are bound to input. Mutually exclusive with input. |
format | How string input is interpreted. auto (default) parses a JSON object or array and binds any other string as-is. text always binds the string as-is. json always parses and fails on invalid JSON. Applies to input_file contents and to a string input. |
timeout | Maximum script run time, as seconds (30) or a duration (2m). Defaults to the step timeout, or 60s when the step has none. |
How It Works
The script is the body of a function that receives one parameter, input. The text is used as written: Dagu does not resolve ${...} references inside it, so JavaScript template literals keep their meaning. Workflow values reach the script through input.
steps:
- id: greet
action: js.run
with:
input:
name: ${params.NAME}
count: 3
script: |
return `Hello ${input.name}, ${input.count} times`;Objects and lists in input arrive as native JavaScript objects and arrays. When neither input nor input_file is set, input is undefined.
Input From Earlier Steps
A captured output: is a string. When it holds a JSON object or array, the default format: auto parses it, so one step's returned object is the next step's input:
steps:
- id: produce
action: js.run
with:
script: |
return {items: ["a", "b"], count: 2};
output: DATA
- id: consume
depends: [produce]
action: js.run
with:
input: ${DATA}
script: |
return input.items.map((item) => item + input.count);Set format: text when the script should see the raw string, and format: json when invalid JSON should fail the step instead of arriving as a string. Only the top-level string is parsed: nested string fields inside an input object stay strings.
Use input_file for larger payloads, such as the stdout log of an earlier step:
steps:
- id: dump
run: cat report.json
- id: summarize
depends: [dump]
action: js.run
with:
input_file: ${dump.stdout}
script: |
return Object.keys(input).length;Output
The returned value is written to stdout, so output: captures it.
| Returned value | Written |
|---|---|
undefined or no return | Nothing |
| String | The string as-is, followed by a newline |
| Any other value | JSON with two-space indentation, followed by a newline |
JSON output follows JavaScript rules: toJSON is honored, Date becomes an ISO string, and function or undefined properties are dropped.
console.log, console.info, console.warn, console.error, and console.debug write to the step's stderr, which keeps stdout clean for the returned value.
Sandbox
Language Level
The engine implements ECMAScript 5.1 in full and the ES2015 through ES2022 language, so modern code runs as written:
- Syntax:
letandconst, arrow functions, template literals, classes withextends, getters, private fields, and static blocks, destructuring, spread and rest, default parameters, generators,asyncandawait, optional chaining?., nullish coalescing??, logical assignment,**, tagged templates, computed keys - Builtins:
Map,Set,WeakMap,Symbol,Proxy,Reflect,BigInt, typed arrays andArrayBuffer,Promise.allandPromise.any,Object.entries,Object.fromEntries,Object.hasOwn,Array.prototype.flat,flatMap,at,findLast,includes,toSorted,with,String.prototype.padStart,replaceAll,matchAll, and the ES2025Setmethods such asunion - Regular expressions: named groups, lookbehind, and the
s,u, andyflags
Not implemented:
- ES modules:
import,export, and dynamicimport() Object.groupBy,Map.groupBy,Promise.withResolvers,Array.fromAsync, the regular expressionvflag,WeakRef,FinalizationRegistry- Host APIs that are not part of ECMAScript:
Intl,structuredClone,TextEncoder,TextDecoder,atob,btoa
Available Globals
URLandURLSearchParamsconsoleawait, for promises that resolve without an event loop. The script body is an async function, soawait Promise.all([...])and async helper functions work. A promise that is still pending when the body returns fails the step, because nothing can resolve it.
Not Available
requireor npm packagesfetch, the filesystem,process, or environment variablessetTimeoutand other timers
Scripts are compiled per run, so there is no shared state between steps.
Limits and Errors
- A script that runs longer than
timeoutfails the step withjs: timeout after 60s; raise with.timeout to allow longer scripts. When the step has its owntimeoutandwith.timeoutis unset, the step timeout governs.dagu stopalso interrupts the script. - A thrown error or rejected promise fails the step. The error names the exception and the script line, such as
js: TypeError: Cannot read property 'x' of null (script line 3), and the full stack trace is written to stderr. Lines and columns match the script text. - A script that returns
undefined, usually becausereturnis missing, succeeds with empty stdout and a notice on stderr. - Memory is not capped. A script that allocates without bound can exhaust the process.
- The interrupt takes effect between JavaScript instructions, so a single long-running builtin call such as a catastrophic regular expression cannot be stopped early.
dagu validaterejects a missingscript, the combination ofinputandinput_file, awithfield the table above does not list, and a script that does not compile, naming the line of the syntax error. An unknown field's error names it and suggests the field it likely misspells, such asdid you mean "input_file" instead of "input_files"?. The editor reports the same errors on save.
Examples
Reshape an API Response
steps:
- id: fetch
action: http.request
with:
method: GET
url: https://api.example.com/users
output: USERS
- id: active_emails
depends: [fetch]
action: js.run
with:
input: ${USERS}
script: |
return input
.filter((user) => user.active)
.map((user) => user.email.toLowerCase())
.sort();
output: EMAILSCompute a Date Range
steps:
- id: range
action: js.run
with:
input:
days: 7
script: |
const end = new Date();
const start = new Date(end.getTime() - input.days * 86400000);
return {
start: start.toISOString().slice(0, 10),
end: end.toISOString().slice(0, 10),
};
output: RANGE
- id: report
depends: [range]
run: ./report --from ${range.output.start} --to ${range.output.end}Normalize Links Before a Loop
steps:
- id: links
action: js.run
with:
input_file: page.html
script: |
const base = "https://example.com";
const urls = new Set();
for (const m of input.matchAll(/href="([^"#]+)"/g)) {
const url = new URL(m[1], base);
if (url.hostname === "example.com") urls.add(url.href);
}
return [...urls];
output: LINKS
- id: crawl
depends: [links]
foreach:
items: ${LINKS}
as: url
steps:
- id: fetch
run: curl -s ${foreach.url} -o /dev/nullNeed Real Node.js?
Use the node-script@v1 action when a script needs Node.js modules, network access, the filesystem, or environment variables. It runs on a Node.js runtime that the action installs.

