Handling results

Read return values and handle failures from resource function calls.

Every resource function call evaluates to a result object with exactly two properties, value and error. A result carries one or the other, never both.

Outcome	value	error
Success	The function’s return value	null
Success, function returns nothing	null	null
Failure	null	{ message: "..." }

On failure, error is an object with a single message string describing what went wrong.

Check for errors first

Because value is null when a call fails, check error before using value:

request CurrentTemperature {
    const weather: com.example.Weather

    const temperature = weather.temperature(city: "Oslo")

    if (temperature.error != null) {
        return temperature.error.message
    }

    return temperature.value
}

If the call succeeds, this returns the temperature. If it fails, it returns the error message, for example "Unknown city".

Why failures don’t stop the script

A failing resource call is something your script can act on: you might fall back to a default, try a different resource or return a friendly message. So a failure is reported in the result, and the script carries on.

request PriceWithFallback {
    const pricing: com.example.Pricing

    const live = pricing.current(sku: "ABC-123")

    var price: decimal = 19.99 // fallback price
    if (live.error == null) {
        price = live.value
    }

    return { price: price, live: live.error == null }
}

A script can’t raise an error of its own. To tell the caller that something failed, return a value that says so, such as { ok: false, reason: live.error.message }.

Mistakes in how a script calls a function, such as a missing argument, a misspelled argument name or a wrongly typed value, aren’t reported in the result. They’re RuntimeErrors that stop the script. See Using resources.

Using the value

value holds a value of the function’s declared return type, and you can use it like any other value:

request Arithmetic {
    const math: path.to.AddResource
    const sum = math.add(first: 2, second: 3)
    return sum.value * 10 // 50
}

Functions that return object produce plain objects. Numbers inside them get inferred types: whole numbers become int32 or int64, and other numbers become decimal.

Functions that return nothing

Some functions perform an action and have no return value. Calling one produces { value: null, error: null } on success, so you can still check error:

request SendWelcome {
    const email: com.example.Email

    const sent = email.send(to: "[e-mail]", subject: "Welcome")

    if (sent.error != null) {
        return "Couldn't send: ${sent.error.message}"
    }

    return "Sent"
}

Returning a result

A result object is an ordinary object, so you can return it directly:

request Raw {
    const math: path.to.AddResource
    return math.add(first: 2, second: 3)
}

{ "returnValue": { "value": 5, "error": null } }