JavaScript (javascript)

Category: actions | Form: | Symbol: Js

Execute JavaScript/Node.js code in a sandboxed environment

Runs JavaScript code in a sandboxed Firecracker VM with Node.js runtime. Put your code in spec.source.code with spec.source.type set to “inline”. Define your entry point using a plain function declaration: async function handler(input) { … } — ES module syntax (export/import) is NOT supported. The runtime looks for handler(), main(), or entrypoint() by name, or a CommonJS export (module.exports = handler). Supports npm dependencies via spec.source.requirements. Also handles TypeScript transparently.

Guide

Execute JavaScript/Node.js code in a sandboxed environment

CommonJS Required (No ES Modules)

JavaScript code runs inside eval() / new Function() in script context, so ES module syntax is not supported. Use CommonJS (require / module.exports) or plain function declarations. If the runtime detects import X from '...', export default, or bare export, it returns a 400 error pointing at the offending line.

// Correct — plain function declaration with optional module.exports
function handler(input) {
  const name = input.name || "World";
  return { greeting: `Hello, ${name}!` };
}
module.exports = handler;

// Correct — CommonJS require for dependencies
const lodash = require("lodash");
function handler(input) {
  return { doubled: lodash.map(input.nums, (n) => n * 2) };
}

// NOT SUPPORTED — ES module syntax will be rejected at submit time
// import lodash from 'lodash';
// export default async function handler(input) { ... }
// export function handler(input) { ... }

The runtime resolves the entry point as handler, main, then entrypoint — either a top-level function declaration or an assignment on module.exports works.

What It Does

JavaScript is a serverless compute element that runs Node.js code inside an isolated Firecracker VM. Unlike the old polyglot function element, the language is the element type — there is no runtime property to configure. Each JavaScript element exports a handler function, supports npm dependencies, and can receive injected connections from attached data elements. TypeScript files are handled transparently via the runtime’s built-in transpilation step.

Code runs with full network egress, a configurable memory ceiling, and per-invocation timeout enforcement. Dependencies are pre-built into cached layers to minimize cold start time.

Element Definition

Property	Value
Type	javascript
Category	functions
Form	atom
Symbol	javascript / #F7DF1E

Properties

Field	Type	Default	Description
handler	string	handler	Export name of the entry point function
source.type	string	inline	Source location: inline, file, or git
source.code	string	—	Inline JavaScript/TypeScript source (for type: inline)
source.path	string	—	File path in workspace (for type: file)
source.repository	string	—	Git URL (for type: git)
source.ref	string	—	Branch, tag, or commit SHA (for type: git)
source.requirements	array	[]	npm dependencies (e.g. ["lodash@4.17"])
memory_mb	integer	128	Memory allocation in MB (64–4096)
timeout_ms	integer	30000	Execution time limit in milliseconds (100–900000)
environment	object	{}	Custom environment variables
layers	array	[]	Additional runtime layers
concurrency.reserved	integer	—	Reserved concurrent execution slots
concurrency.max	integer	—	Maximum concurrent executions
retry.max_attempts	integer	3	Retry attempts on failure
retry.backoff_ms	integer	1000	Initial backoff delay in ms
retry.backoff_multiplier	number	2.0	Exponential backoff multiplier

Ports

Direction	Port	Required	Description
Input	payload	Yes	JSON input passed to the handler function
Output	result	—	Handler return value as JSON
Output	error	—	Error details if execution failed

Capabilities

Capability	Description
zero-scale	Scales to zero when idle
streaming	Supports output streaming
env-injection	Data resources injected as environment variables
npm-dependencies	Supports npm package dependencies

Input Contract

Your handler receives the caller’s payload as a plain JavaScript object. The platform automatically unwraps common envelope patterns (payload, data, input keys) and strips internal metadata, so your handler always sees the clean user data.

Direct invoke — the JSON body is passed through:

POST /api/{circle}/my-fn/ops/invoke
{"name": "Alice", "count": 3}

function handler(input) {
  // input = {name: "Alice", count: 3}
  return { greeting: `Hello, ${input.name}!` };
}

Envelope invoke — the platform unwraps payload/data/input keys automatically:

POST /api/{circle}/my-fn/ops/invoke
{"payload": {"name": "Alice"}}

// handler still receives {name: "Alice"} — envelope is stripped

Wired invoke (from automation steps or other elements) — the orchestrator shapes inputs based on port topology. Your handler receives the resolved payload, not raw wire data.

Quick Start

Creating via API

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "javascript",
  "slug": "my-js-fn",
  "name": "My JS Function",
  "spec": {
    "source": {
      "type": "inline",
      "code": "async function handler(input) {\n  return { message: `Hello, ${input.name || 'World'}!` };\n}\nmodule.exports = handler;"
    },
    "memory_mb": 128,
    "timeout_ms": 10000
  }
}

Invoking

POST /api/{circle}/{project}/my-js-fn/ops/invoke
Content-Type: application/json

{
  "payload": { "name": "Triform" }
}

Writing Handler Functions

The handler can be a plain function declaration or an async function. It receives the input payload as a plain JavaScript object:

async function handler(input) {
  // input is a plain object — the JSON payload from the invoke call
  const { name = "World", count = 1 } = input;

  const results = Array.from({ length: count }, (_, i) =>
    `Hello ${name} #${i + 1}`
  );

  return {
    results,
    total: count
  };
}

CommonJS Syntax (required)

Functions must use CommonJS or plain declarations — ES module syntax (import, export, export default) is rejected with a 400 error at submit time:

// Correct — plain function declaration (the runtime resolves `handler` by name)
function handler(input) { ... }
async function handler(input) { ... }

// Correct — CommonJS export
function handler(input) { ... }
module.exports = handler;

// Correct — CommonJS require for dependencies
const axios = require("axios");

// Not supported — these return a 400 "ES modules not supported" error
// import axios from 'axios';
// export async function handler(input) { ... }
// export default async function(input) { ... }

TypeScript Support

TypeScript files are transpiled transparently. Write .ts files and the runtime handles compilation. Use plain function declarations — CommonJS-style — not ES module exports:

interface Input {
  name: string;
  count?: number;
}

interface Output {
  results: string[];
  total: number;
}

async function handler(input: Input): Promise<Output> {
  const { name, count = 1 } = input;
  return {
    results: Array.from({ length: count }, (_, i) => `Hello ${name} #${i + 1}`),
    total: count
  };
}
module.exports = handler;

Entry Point Resolution

If spec.handler is not set, the runtime resolves the entry point in this order:

1. Global function handler
2. Global function main
3. Global function entrypoint

Using npm Dependencies

List dependencies in spec.source.requirements. They are resolved at build time and cached as a layer:

{
  "spec": {
    "source": {
      "type": "inline",
      "code": "...",
      "requirements": ["axios@1.6.0", "zod@3.22.0"]
    }
  }
}

Pre-build the dependency layer to avoid cold start penalty:

POST /api/{circle}/{project}/my-js-fn/ops/build

Attaching Data Resources

Data elements (sql, document, vector) are injected as environment variables:

POST /api/{circle}/{project}/my-database/ops/attach
Content-Type: application/json

{ "target_id": "<javascript-element-uuid>" }

Inside the handler, access the injected connection strings:

async function handler(input) {
  const dbUrl = process.env.RESOURCE_SQL_MY_DATABASE;
  // use dbUrl to connect to the database
  return { connected: !!dbUrl };
}
module.exports = handler;

Resource	Environment variable pattern
sql	RESOURCE_SQL_{SLUG_UPPER}
document	RESOURCE_DOCUMENT_{SLUG_UPPER}
vector	RESOURCE_VECTOR_{SLUG_UPPER}
graph	RESOURCE_GRAPH_{SLUG_UPPER}
timeseries	RESOURCE_TIMESERIES_{SLUG_UPPER}

Common Mistakes

Putting code at the wrong path. Code must be in spec.source.code, not spec.code. The source object wraps all source-related fields.

Using ES module syntax instead of CommonJS. The runtime rejects ES module syntax at submit time with a 400 error. Use plain function declarations or module.exports = handler; — never export default or import X from 'pkg'. Use require("pkg") for dependencies.

Forgetting to declare the handler at top level. The runtime resolves the entry point by scanning global declarations for handler, main, and entrypoint (in that order). A function defined inside another function or a block scope will not be visible.

Not pre-building dependencies. Without a cached layer, every cold start runs npm install from scratch. For functions with many dependencies, call the build operation first.

Expecting synchronous return values. All handlers must be async (return a Promise). Synchronous functions returning plain values are wrapped automatically, but unexpected behavior can occur with synchronous error throws.

Relationships

• Attaches to: rate-limit, auth-policy, validation, filter-words, evaluator
• Uses: prompt, variable, sql, document, vector, graph, timeseries

Capabilities

• zero-scale: Scales to zero when idle
• streaming: Supports output streaming
• env-injection: Data resources injected as environment variables
• npm-dependencies: Supports npm package dependencies

Properties

Property	Type	Default	Description
handler	string	—	Entry point function name. Default: handler() -> main() -> entrypoint(). Use a plain function declaration: async function handler(input) { … } CommonJS exports also work: module.exports = handler; or exports.handler = handler; ES module syntax (export async function / export default) is NOT supported.
source	object	—	Source code location. For inline code use type=“inline” with code in the “code” field. IMPORTANT: code goes in spec.source.code (NOT spec.code).
memory_mb	integer	128	Memory allocation in MB
timeout_ms	integer	30000	Maximum execution time in milliseconds
environment	object	—	Custom environment variables injected at runtime
layers	array	[]	Additional runtime layers
concurrency	object	—	Controls how many copies can run simultaneously
retry	object	—	Automatic retry on failure

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this actor to a target element

Call this ON the modifier/resource element, passing target_id of the actor. The target’s contract.yaml must declare the modifier kind in attaches: or uses:. Priority controls evaluation order for modifiers (lower = first).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

build

Post /ops/build | Auth: Execute

Install npm dependencies and create a cached layer

Pre-builds npm dependencies and caches them as a layer. Subsequent invocations skip npm install. Use force=true to rebuild even if a cached layer exists.

build_status

Get /ops/build/{build_id} | Auth: Read

Check the status of a build

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this actor from a target element

diagnostics

Get /ops/diagnostics | Auth: Read

Check isolation service connectivity and health

Returns the status of the isolation executor that this element depends on for code execution. Use this to distinguish between user code errors and infrastructure issues when invoke returns 500. Returns isolation_reachable (bool), worker_available (bool), and last_error if any.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this action

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Execute the JavaScript function with an input payload

Main entry point for JavaScript function execution. Requires a JSON payload. Returns invocation_id for async tracking. Input contract: your handler receives the caller’s data as a plain JavaScript object. The platform auto-unwraps envelope keys (payload, data, input) so you always get the clean payload. Example: function handler(input) { return { greeting: “Hello, “ + input.name }; }

list_attachments

Get /ops/targets | Auth: Read

List all elements this action is attached to

Returns all target elements where this action is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Get execution logs

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_cancel

Post /ops/runs/{run_id}/cancel | Auth: Execute

Cancel a running execution

Only works on runs with status pending or running. Already-completed or failed runs cannot be cancelled. The run transitions to cancelled state and triggers run.cancelled event.

run_get

Get /ops/runs/{invocation_id} | Auth: Read

Get details of a specific invocation

runs

Get /ops/runs | Auth: Read

List invocation history

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Call this before invoking an actor to discover its expected input/output format. Returns MCP-compatible tool definitions — useful for building dynamic tool UIs or A2A integration.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

test

Post /ops/test | Auth: Execute

Run the function’s test suite

Executes tests defined alongside the function source. Supports Jest and Node.js test runner. Filter with test_filter to run a subset of tests. Returns test_run_id for async status tracking.

test_status

Get /ops/test/{test_run_id} | Auth: Read

Check the status of a test run

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
JAVASCRIPT_TIMEOUT	timeout	yes	Execution exceeded timeout_ms
JAVASCRIPT_OOM	internal	no	Out of memory (exceeded memory_mb)
JAVASCRIPT_SYNTAX_ERROR	validation	no	JavaScript/TypeScript syntax error in source code
JAVASCRIPT_MODULE_NOT_FOUND	internal	no	Failed to resolve required npm dependency
JAVASCRIPT_RUNTIME_ERROR	internal	no	Unhandled exception during JavaScript execution