Events: declare, emit and consume

​

Declaring an event type

event shop.OrderPlaced@1(orderId: string, total: decimal)

• The path, name and version work as they do for contracts. The version defaults to 1.
• Fields are name: type pairs, like contract parameters, with any type. Field names must be unique.
• An event type without fields leaves out the parentheses: event shop.Tick.
• An event declaration can’t have a body or a return type. Either one is a parse error.

restricted event shop.InternalAudit(entry: object)

​

Emitting an event

contract shop.Checkout(orderId: string, total: decimal): string {
    emit shop.OrderPlaced(orderId: orderId, total: total)
    return orderId
}

• Name the event type as path.Name, or path.Name@version to pin a version. Without a version, the host picks one.
• Pass every field by name, in any order. A missing field, or a field the event type doesn’t declare, is a runtime error.
• Each value is converted to its field’s type, as an argument to a resource function is. A value that doesn’t fit is a runtime error.
• emit can appear anywhere a statement can, including inside if branches. Its tokens are counted like any statement’s.

​

Consuming events

contract shop.OnOrderPlaced consumes shop.OrderPlaced@1 {
    var state(orderId) seen: int32 = 0
    seen = seen + 1
}

• An event contract declares no parameters. The event’s fields are its parameters, readable by name, like const parameters.
• It has no return type and can’t return a value. A bare return ends it, and return with a value is a parse error.
• consumes names the event type as path.Name or path.Name@version.
• An event contract can keep state variables and call resources like any contract.

​

Reserved words

request Names {
    var emit = 1
    var event = { consumes: 2 }
    return emit + event.consumes
}

​

Hosting events

import { interpret, type EventResolver } from "requestscript";

const events: EventResolver = {
  // Returns { path, name, version, fields: [{ name, type }] }, or undefined for an unknown type.
  resolve: async (path, name, version) => lookup(path, name, version),
};

const result = await interpret(source, { events, parameters });
await publish(result.events); // [{ path, name, version, data }]

• data holds each field’s value as JSON, encoded as in JSON encoding.
• Without a resolver, emit and running an event contract are runtime errors.
• A resolver can refuse an event by throwing a RuntimeError, which fails the script with its message. Hosts use this to decide who may emit what.
• emittedEvents(script) lists every event type a script’s emit statements name, including those in branches that may not run, so a host can check a script before it accepts it.