Skip to main content

Math and Wait Utilities

Two small helpers round out the library: mathUtils for arithmetic and random numbers, and waitUtils for pausing execution. Unlike the other helpers, these return plain values — no JSON envelopes to parse.

mathUtils​

Arithmetic that returns numbers directly. JavaScript's own Math and operators cover most of this too; mathUtils is useful when inputs arrive as strings (as tool variables always do) and for its explicit failure modes.

  • Name
    mathUtils.add
    Type
    (a: number | string, b: number | string) => number
    Description

    Adds two values. The string-accepting overload parses each argument as a number first — handy for variables.get(...) values without an explicit parseFloat. Non-numeric strings throw.

  • Name
    mathUtils.subtract
    Type
    (a: number, b: number) => number
    Description

    Returns a - b.

  • Name
    mathUtils.multiply
    Type
    (a: number, b: number) => number
    Description

    Returns a * b.

  • Name
    mathUtils.divide
    Type
    (a: number, b: number) => number
    Description

    Returns a / b. Throws an error on division by zero (unlike JavaScript's / operator, which returns Infinity).

  • Name
    mathUtils.power
    Type
    (base: number, exponent: number) => number
    Description

    Returns base raised to exponent.

  • Name
    mathUtils.sqrt
    Type
    (value: number) => number
    Description

    Square root. Throws an error for negative input (unlike Math.sqrt, which returns NaN).

  • Name
    mathUtils.random
    Type
    () => number
    Description

    Random number in [0, 1).

  • Name
    mathUtils.randomBetween
    Type
    (min: number, max: number) => number
    Description

    Random number in [min, max).

const price = mathUtils.add(variables.get("basePrice"), variables.get("surcharge")); // strings ok
const perUnit = mathUtils.divide(price, parseInt(variables.get("quantity")));        // throws if quantity is "0"
response.setResponse(JSON.stringify({ perUnit: perUnit.toFixed(2) }));

mathUtils.divide and mathUtils.sqrt throw real errors instead of returning Infinity/NaN. That's a feature — a thrown error fails the execution loudly instead of letting a silent NaN propagate into your result — but wrap them in try/catch if you want to handle the case yourself.

waitUtils​

  • Name
    waitUtils.sleep
    Type
    (milliseconds: number) => void
    Description

    Blocks the script for the given number of milliseconds. Throws an error if the wait is interrupted by the platform.

There is no cap on the argument itself, but sleeping is never free: the script is fully blocked while it sleeps, and the time counts against the surrounding execution's overall time budget. Keep sleeps short — polling backoff between api.* calls is the intended use:

let status = "pending";
for (let attempt = 0; attempt < 5 && status === "pending"; attempt++) {
  if (attempt > 0) waitUtils.sleep(2000);   // 2s between polls
  const res = JSON.parse(api.get(JSON.stringify({ endpoint: jobUrl })));
  status = JSON.parse(res.body).status;
  console.log("attempt", attempt + 1, "status:", status);
}
response.setResponse(JSON.stringify({ status: status }));

Remember that setTimeout does not exist in the sandbox — waitUtils.sleep is the only way to pause, and it pauses everything.