Symbols
A symbol is one exported name and the statements that declare it. An output does not write files. It declares symbols, and the symbol registry prints one file for each path that has at least one symbol. The registry also writes the import declarations between those files.
yield* registry.declare({
capability: "types:row:Users", // unique id in the run: <output>:<kind>:<name>
name: "Users", // the exported identifier
file: "types.ts", // the symbol's default file name
entity: Option.some("public.users"), // the entity it derives from; Option.none() when shared
kind: "type", // a "type" symbol is imported type-only
statements: [c.exportInterface("Users", members)],
imports: [{ from: "effect", types: ["Schema"] }], // packages the statements use
})
Capabilities
A capability is the id other outputs use to ask for a symbol. It starts with the owning output and a colon, so two outputs may export the same name from different files. The registry rejects two failures:
DuplicateCapability: one capability is declared twice.SymbolCollision: two symbols export one name from one file. The check uses the path the layout gives the file.
Layout
A symbol says what it is: its owner, its default file name and its entity. The Layout service turns that into a path. The default layout writes the symbols of one entity to <schema>/<table>/<file> and leaves shared symbols in file. The byKind() plugin writes each symbol to its file. The authoring guide shows how to write a layout.
Two phases
An output runs in two phases. The generator runs every declare phase first, then every link phase, so the order of outputs does not matter.
- Declare. The output reads the semantic model and the plans, and calls
registry.declare. - Link. The output asks for symbols it uses with
registry.import(capability, { into, type? }). Imports belong to symbols:intois the capability of the symbol that uses the imported one. The registry records the use and writes the import in the importing symbol's file, with the right relative path.UnknownCapabilityis the failure when no selected output declared it.registry.importOptionalreturnsOption.none()instead of failing.
An output has the type Output: the outer effect declares, and the effect it returns links and yields the documents the output writes itself, which is none when the registry prints its files. noLink is the link step of an output that imports nothing from another generated file. The authoring guide shows a complete output and its test.