JavaScript steps

A JavaScript code step runs on your Mac in QueryLane's Node.js runtime. It has access to files, the network, processes and installed npm packages, so run only code you trust.

How the code runs

The code is the body of an async function. Use await freely and return the value that should become the step result. Without return, the result is undefined.

The step has 30 seconds by default. Set Execution timeout (ms) for longer work, up to 24 hours.

Use step results and variables

Before the code runs, QueryLane replaces each token with a value:

• ${step_id} becomes the data of that step as a JSON literal: an array of SQL rows, an API response body, a returned object and so on. Dates in the data arrive as ISO strings.
• A Number variable is inserted as a number.
• A Date variable becomes new Date("...").
• A String variable is inserted as raw text, so put it in quotes: const region = '${region}';.

All variables are also available in the variables object, for example variables.region.

Insert step tokens from Step results: in the editor. Ids created in the editor are long, such as step_4f0c..., and the examples on this page use short readable ids instead.

Globals

The code can use the standard JavaScript built-ins and these globals:

• console. Output goes to the QueryLane log files, not to the run result.
• setTimeout, setInterval, clearTimeout and clearInterval.
• require, process, Buffer, __dirname and __filename.
• variables, the job variables.

Web APIs such as fetch are not globals here. Load what you need with require: Node.js modules such as node:fs and node:path, and the packages bundled with QueryLane. They include dayjs, csv-parse, csv-stringify, exceljs, xlsx, yaml, zod, undici, pg, mysql2, mongodb and @clickhouse/client. For HTTP, use const { fetch } = require('undici');.

Example

A SQL step step_orders returns orders with customer_id, amount and created_at. This step totals them per customer:

const dayjs = require('dayjs');
const orders = ${step_orders};

const totals = new Map();
for (const order of orders) {
  const sum = totals.get(order.customer_id) ?? 0;
  totals.set(order.customer_id, sum + Number(order.amount));
}

return [...totals].map(([customerId, total]) => ({
  customer_id: customerId,
  total: Math.round(total * 100) / 100,
  report_date: dayjs().format('YYYY-MM-DD'),
}));

The result is an array of rows, so the next step can load it into a table or send it to an API, and you can add result checks to it.

Install npm packages

1. Open Settings > Dependencies.
2. Under Install, enter the package name and, if needed, a version. Leave the version empty for the latest one.
3. Click Install package.

Installed packages appear under Installed packages. You can delete them there; the packages bundled with QueryLane are not listed and cannot be deleted.

For a private registry, put your registry settings and tokens in the .npmrc field under Configuration before you install:

@acme:registry=https://npm.acme.dev/
//npm.acme.dev/:_authToken=YOUR_TOKEN

If a step imports a package that is not installed, the run fails with NPM package is not available, and the run in Execution history offers a button such as Install lodash.

npm on your Mac

QueryLane uses npm to install packages, and the Node.js runtime inside the app does not include npm. Install Node.js with npm on your Mac, for example with Homebrew or nvm. QueryLane looks for npm:

• next to the Node.js set in Settings > General > Node.js executable, if you set one;
• in ~/.nvm/versions/node/<version>/bin/npm;
• in /usr/local/bin/npm, /opt/homebrew/bin/npm and /usr/bin/npm.

If it finds none, installing fails with npm executable was not found.

Import or global

Use an import line at the top of the step for installed packages:

import { chunk } from 'lodash';

return chunk(${step_orders}, 500);

Each installed package is also a global without an import. Its name is __pkg_ followed by the package name without the leading @ and with /, - and . replaced by _: lodash is __pkg_lodash, @faker-js/faker is __pkg_faker_js_faker. import is easier to read.

import works only for packages installed in Settings > Dependencies. Load bundled packages and Node.js modules with require.