Using resources

Bind a resource and call its functions with named arguments.

A resource is a named set of functions that the server makes available to scripts. Resources are how scripts reach beyond plain computation: reading data, calling other services or performing actions.

Which resources exist depends on the server you’re using. Each one has a dotted path and a name, such as com.example.Weather, and each function has named, typed parameters and a return type. Ask your server’s administrator for the resources available to you.

request AddNumbers {
    const math: path.to.AddResource

    const sum = math.add(first: 2, second: 3)

    return sum.value // 5
}

Bind a resource

To use a resource, bind it to a name with a const declaration whose type is the resource’s full path and name:

const weather: com.example.Weather

• Resource bindings must use const, not var.
• A resource binding has no = value.
• The resource is looked up when the declaration runs. If the server has no resource with that path and name, the script fails with Unknown resource 'com.example.Weather'.

You can bind as many resources as you need, and bind them anywhere a declaration is allowed.

Call a function

Call a function on a bound resource with dot notation and named arguments:

const sum = math.add(first: 2, second: 3)

Arguments are always passed by name, so their order doesn’t matter. This call is equivalent:

const sum = math.add(second: 3, first: 2)

Every argument is checked against the function’s declaration before the function runs:

• Every declared parameter must be passed: Missing argument 'city' for function 'temperature'.
• Unknown or duplicate argument names are errors.
• Each argument must match its parameter’s type, with numeric promotion applied: Cannot use a int32 value as string for argument 'city' of 'temperature'.

These mistakes are RuntimeErrors that stop the script, because they’re bugs in the script rather than conditions it can recover from.

Use the result

A function call never evaluates to the bare return value. It always evaluates to a result object with a value and an error:

{ value: 5, error: null }                          // success
{ value: null, error: { message: "timed out" } }   // failure

Read the return value from .value, and check .error first if the call can fail:

request CurrentTemperature {
    const weather: com.example.Weather

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

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

    return temperature.value
}

See Handling results for the full details.

Call a function for its side effect

If you don’t need a function’s result, call it as a statement on its own:

request Notify {
    const audit: com.example.Audit
    audit.log(message: "Report generated")
    return "done"
}

If the call fails, the failure is discarded along with the result and the script continues. Store the result and check .error if the outcome matters.

Resource references aren’t values

A bound resource can only be used to call its functions. You can’t:

• Return it, or store it in an object or list.
• Interpolate it into a string.
• Read a function without calling it, such as weather.temperature.

Doing any of these is an error: A resource reference cannot be used as a value.