Skip to main content

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.

  1. Declare. The output reads the semantic model and the plans, and calls registry.declare.
  2. Link. The output asks for symbols it uses with registry.import(capability, { into, type? }). Imports belong to symbols: into is 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. UnknownCapability is the failure when no selected output declared it. registry.importOptional returns Option.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.