Skip to main content

interface

Attribute Macro interface 

Source
#[interface]
Expand description

Declare an INTERFACE — a member set with a contract over it.

An interface is a union plus a promise. The union half is the same payload-carrying enum Union equips: one variant per member, each carrying that member and nothing else. The promise is fields(…) — every member has these fields, at these types.

ⓘ
#[ingraph::interface(
  persist(sqlite, postgres),
  graphql(computed(error = "media::ComputeError")),
  fields(
    title: String,
    mask(type = "Mask", copy, persist(sqlite(type = "u32"), postgres(type = "int4"))),
    created_at(type = "Timestamp", members(Audio(field = "imported_at"))),
    display_label(type = "String", graphql(computed)),
    checksum(type = "u64", graphql(try_computed)),
  ),
)]
pub enum Media {
  Video(Video),
  Audio(Audio),
}

§A field is in ONE of three tiers, and the tier decides whose face carries it

tierwrittenevery memberthe face
storednothing, or persist(<db>(type = "…"))carries the column<I>Fields, on the member
computedgraphql(computed)DERIVES the value<I>Derivations, on its wire output
try_computedgraphql(try_computed)derives it, falliblythe same, returning a Result

The domain contract is STORED-ONLY. A computed field is a query-layer construct — it is derived to be answered, and what answers a query is the wire output — so putting one on the domain trait would make every member’s domain type owe a method its rows have no column for. <I>Derivations is DECLARED and implemented nowhere: a member’s output type writes the impl by hand, and there is no adapter under it, because a hand author writes their own glue.

Stored and computed are mutually exclusive in both directions, and each direction has its own refusal.

§Attributes

On the enum:

  • crate = "path::to::ingraph" — where ingraph lives, exactly as record’s. Present here where a union has none, because an interface’s expansion DOES name framework paths: the membership evidence, the storability its equations read a row through, and the backend gates they ride.
  • unwrap_error(rename = "Name") — what the emitted REFUSAL type is called. Defaults to <Interface>UnwrapError, which is the union’s convention reached through the union’s own function. error names the CONVERSION CELLS instead, and the old spelling is a named migration refusal — one word per thing typed.
  • persist(sqlite, postgres, …) — which databases the contract’s pins are checked at. A SELECTION rather than a storage declaration: an interface owns no table. A database block may carry alias(prefix = "__mine"), which moves the words a union statement INVENTS in that database — the discriminant every arm projects and the derived table the outer query names. depth is refused here: it is the length of an alias table, and an interface has none.
  • graphql(computed(error = "path::To")) — the type every fallible computed field answers with. ONE cell and DB-LESS, which is this grammar’s one ruled exception to database blocks: a computed value is derived from the member rather than read out of a row, so the crossing names no database.
  • fields(…) — the contract. An interface with none is a union, and is refused by that reason.

A field is <name>: <Type> or <name>(type = "<Type>", …), and the long form takes copy, persist(<db>(type = "…")), graphql(…) and a MEMBER block. The long form’s type is written in a STRING, as every other type in this grammar is; the short form’s is the Rust type itself, because there it is what the : already introduces.

§A member may call a stored field something else

created_at(type = "Timestamp", members(Audio(field = "imported_at"))) — the member Audio carries this field as imported_at, in its own struct and in its own row.

Declared on the INTERFACE rather than on the member, and the reason is what a macro can see: a member-side word would have to reach the interface’s expansion across a derive boundary, and the only things that cross one are a type and a const — neither of which produces the IDENT a field access needs. Written here, every hop is backed by the same derive input, starting with the block’s key, which is checked token-for-token against the enum’s own variants in VERBATIM case.

What a block moves is the ACCESS and not the METHOD: a caller writes the interface’s name whatever member it is holding. field = "…" is the only entry it takes; one members(…) per field, never empty; and members(…) on a computed field is refused — a derived value is read out of no column at all.

§The axis law

A DOMAIN block, then a DATABASE block, then that cell’s entries — at every level. So a database name written where a domain belongs is refused BY NAME rather than as an unknown entry, wherever it appears.

A field’s members(…) extends it one step — interface field block ▸ members(…) ▸ one block per variant ▸ entries — and the step is this grammar’s alone: a record grows no member axis, having no members.

POSITION decides what a key is. Outside members(…) every key is a word this grammar owns; inside it every key is a VARIANT, matched token-for-token against the enum’s own. A variant written outside the container is refused BY NAME rather than as an unknown word, and one whose spelling collides with a grammar word — or one in lower case — is reachable inside it, where a rule reading the first letter had a corner it could not address.

§What it emits

The union face — is_<member>, the unwrap_<member> family in all three receivers, and the sealed refusal — through the same seam Union reaches, so an interface’s members are asked for exactly as a union’s are.

§Refusals

The SHAPE refusals are the union’s family, stated in this declaration’s own terms: a non-enum, an enum with no variants, a variant carrying no member, one carrying several, one carrying its member in a named field, any generic parameter, two variants carrying one type, and two variants whose words derive one method.

Its own are the contract’s: a field declared twice, a field with no type, an entry neither form admits, a database name at a domain position, an interface with no fields(…) at all, and the tier collision in both of its directions. members(…) adds five more — a key naming no variant (refused by listing the ones there are), one member named twice in one container, a container on a computed field, a second container on one field, and one naming nobody. A member block written OUTSIDE the container is refused by name, which is a migration rather than an unknown word.

A field’s graphql(output(<db>(…))) is ADMITTED AND REFUSED rather than unknown: it is a real entry of the settled design whose consumer is the interface’s own output face, whose stored half waits on an accessor a member’s wire object does not publish yet, so the refusal names the shape and says what it arrives with. The four operand and hydration cells beside it are READ — see [interface]’s own note for which level each sits at and why.