JsCode

JsCode is a simple tool that lets you write JavaScript to transform data, call external APIs, or build a reusable tool that other parts of your workflow can use. It runs inside the Nappai dashboard, so you can mix it with other components without writing any code outside the platform.

How it Works

When you drop JsCode into a workflow, you give it two main things: the data you want to work on and a block of JavaScript. The component then runs that code in a sandboxed environment.

• $data – the input data you supplied.
• $args – arguments that are passed when the component is used as a tool.
• $components – a map of outputs from other components (only available when the component is part of a workflow, not when it’s used as a tool).
• $log(…) – a helper that writes a message to the component’s log.
• $fetch(url, options) – a synchronous HTTP request helper that returns a JSON object with the response details.

The code must finish with a return statement. Whatever you return becomes the component’s Processed Data output. If you want the component to act as a tool that other parts of the system can call, you also provide a Tool Name, Tool Description, and a Tool Input Schema; the component will expose a tool that accepts those arguments and runs the same JavaScript.

The sandbox limits you to:

• 10 seconds of execution time per run
• 10 calls to $fetch per run
• 1,000 items for list outputs and 150 KB for text outputs
• 50 calls to $log per run

These limits keep the system responsive and prevent runaway scripts.

Inputs

• Input Data: The data you want to process. It can be a single value or a list. If you need to pull data from the web, you can use $fetch inside your JavaScript instead of putting it here.

• JavaScript Code: The JavaScript that will run. Use $data to access the input data, $args for tool arguments, $components to read other component outputs, $log(...) to write logs, and $fetch(url, options) to call external APIs.
  Example:

  // Return the input unchanged
  return $data;

• Tool Input Schema: A JSON schema that describes the arguments the tool will accept. This schema is added to the $args variable when the tool is called.

• Tool Description: A short text that explains what the tool does. It is shown to users when they select the tool.

• Tool Name: The name that will appear in the tool list. It must be unique within the workflow.

Outputs

• Processed Data: The value returned by your JavaScript code. It can be any JSON‑serializable type (object, array, string, number, etc.).

• Tool: A tool object that can be invoked by other components or by the LLM. It contains the name, description, input schema, and the JavaScript code you supplied.

Usage Example

Suppose you want to fetch a list of products from a public API, filter out the ones that are out of stock, and expose the result as a tool.

1. Input Data – leave empty or put a placeholder value.
2. JavaScript Code – paste the following:

   // Fetch products
   const response = $fetch("https://dummyjson.com/products");
   if (!response.ok) {
     $log("Failed to fetch products:", response.statusText);
     return [];
   }
   
   // Filter in‑stock products
   const inStock = response.data.products.filter(p => p.stock > 0);
   
   // Return the filtered list
   return inStock;

3. Tool Input Schema – leave empty (no arguments needed).
4. Tool Description – Return a list of products that are currently in stock.
5. Tool Name – Get In‑Stock Products.

Now you can drag the Tool output into any other component that accepts a tool, or call it directly from the LLM. The Processed Data output will contain the filtered list and can be used by downstream components.

Tips and Best Practices

• Keep code short – the sandbox is limited to 10 seconds; long loops or heavy computations may time out.
• Use $fetch sparingly – you’re limited to 10 calls per run; batch requests if possible.
• Validate input – check that $data is the type you expect before processing to avoid runtime errors.
• Log wisely – $log is useful for debugging, but each call counts toward the 50‑call limit.
• Return simple structures – large or deeply nested objects can hit the 150 KB limit.
• Test in isolation – use the “Run” button in the dashboard to see the output before wiring the component into a workflow.

Security Considerations

• Sandboxed execution – the JavaScript runs in a restricted environment; it cannot access the file system or arbitrary system resources.
• Network calls – $fetch only allows HTTP/HTTPS requests; the component cannot open sockets or run arbitrary protocols.
• No external code execution – only the code you paste is executed; the system does not download or run external scripts.
• Input validation – always validate $args and $data to avoid injection or malformed data that could break downstream components.

---