Realms in TypeScript

A TypeScript realm is one realm.ts file that describes the whole realm as a typed object, plus the handler code it runs. defineRealm from @embabel/realm-types checks the object while you write it, and realm-synth from the same repository turns it into the files this specification describes: realm.yml, dist/manifest.json, producers/, channels/, apps/ and the rest. It also writes the TypeScript types the handlers import. The host never reads realm.ts. It reads what synth wrote.

This document covers realms written with execution: "captured". A captured realm runs from a verified copy the owner has admitted, and every capability it reaches is approved by the owner on its own. For each part of a realm it shows what you write, what synth accepts and refuses, and what the host does with it. The host-side detail lives in hosted execution, and each section here links to its part of it.

The rules for a conventional realm (no execution, or execution: "conventional") are the rest of this specification. The two never mix: triggers, queries, apps, credentials, dataPipes, capturedLenses, watches and graphql are refused on a conventional realm, and goals, producers, apis and channels take the captured forms described here once execution is "captured".

Most examples below come from one realm, oncall-radar, which reads a status page API and tells the owner what is down. Channels, dependencies and data pipes use small realms of their own.