Built-in variables

A built-in variable is a value the host running your script passes in. You read it like any variable, but you don’t declare it. Which built-ins exist depends on the host. A Stellarium node, for example, passes the caller’s run token as jwt.

request WhoAmI {
    return jwt.sub // a field of the built-in jwt object
}

Built-ins are read-only

A built-in can’t be reassigned, and unlike a const its contents can’t be changed either:

request ReadOnly {
    jwt = null          // Error: Cannot assign to 'jwt' because it is a const
    jwt.sub = "other"   // Error: Cannot set property 'sub' because the object is read-only
}

This holds at every depth, for objects and lists inside the built-in too. A variable you assign a built-in to refers to the same read-only value. To work with a field, copy it into a variable of its own:

request CopyField {
    var label = jwt.sub
    label = label + " (via script)" // OK: label is an ordinary var
    return label
}

Built-in names are reserved

You can’t declare a variable with a built-in’s name, in any scope:

request Reserved {
    var jwt = 1 // Error: 'jwt' is a built-in variable and cannot be redeclared
}

A contract can’t have a parameter with a built-in’s name either. That is a parameter error. A built-in can be null. For example, a host may pass jwt as null when the caller didn’t use a token. Its name is still reserved:

request Caller {
    if (jwt == null) {
        return "anonymous"
    }
    return jwt.sub
}

Types

Built-ins are converted the same way as resource results: whole numbers become int32 or int64, other numbers decimal, and objects and lists are converted field by field. See Types.

Passing built-ins from a host

Hosts pass built-ins with the builtins option of interpret or interpretParsed (requestscript 1.3.0 and later):

import { interpret } from "requestscript";

const result = await interpret(source, {
  builtins: { jwt: { sub: "cli_123", org: "org_456" } },
});

Each name must be an identifier, and not a keyword. The interpreter copies the values, so a script never changes the host’s objects.

Get started

Language

Resources

Contracts

Reference

Built-ins are read-only

Built-in names are reserved

Types

Passing built-ins from a host

​Built-ins are read-only

​Built-in names are reserved

​Types

​Passing built-ins from a host

Built-ins are read-only

Built-in names are reserved

Types

Passing built-ins from a host