Skip to main content

Crate ingraph_derive

Crate ingraph_derive 

Source
Expand description

The macros for ingraph.

These expand a declaration into the framework faces a record must implement — Transformer, the per-backend record impls and the query bindings. They generate framework faces only: domain validation, constructor invariants and the error enums that mirror them belong to the application’s own types.

Today they expand the key TYPES and the binding that ties them to the record. [Record] emits *Key, *Lineage, impl Transformer for <Record> and the Identifiable supertrait it cannot be written without — on the record and on the *Key both, the two types carrying the same id column. The rest of the trait layer is still moving, and an expansion naming a half-settled trait would owe every consumer a revision the moment it settled — so the other impls wait. Those two are not among them: their faces are the expansion’s own output and the record it sits on, so they name nothing that could settle differently.

§THE FORM IS AN ATTRIBUTE, because these macros rewrite the item they sit on

A derive is handed a copy of the declaration and may only APPEND. These need to change it — a derived index carries an identity it does not mint, as one field whose TYPE is a projection, and that field has to be in the struct rather than beside it — so the whole family is attribute macros and the declaration’s own options are the attribute’s ARGUMENTS:

ⓘ
#[ingraph::record(sqlite, lineage(fields(media_id)))]
pub struct VideoTrack { … }

The second thing the form buys is the VISIBILITY CONVENTION: a field written with no visibility is stamped pub(crate) by the macro, and an author’s explicit visibility is preserved, so the rule stops being the author’s pen. See [host] for the whole of what an echo changes and the much longer list of what it carries verbatim.

§ONE NODE HOLDS ONE STORAGE, so the macro IS the storage declaration

operator is the node family’s base — it subscribes, it computes, it emits, and it owns no storage — and every other node macro is it plus exactly one store: record holds rows in the databases its store words name, [aggregate] holds rows a declared FOLD over one upstream’s rows fills, and fulltext, vector and blob each hold documents derived from another node’s messages. So there is no word on a declaration that says which storage it has; the attribute’s own name is that word, which is one layer fewer and one contradiction fewer.

The family splits again one level down, and the axis is the KEY rather than the store. A record, an aggregate and an operator MINT an id — an aggregate’s from the group columns it projects; the three derived indexes mint none and carry their upstream’s key in a field this crate injects. That is the second thing the attribute form buys, and the reason the three could not arrive before upstream(…) did.

The two halves of the law are enforced in the two places they can be. The block a node may write is checked HERE, against the macro it was written under, and every other storage block is refused by a message naming the declaration that takes it. That a node does not take a SECOND macro cannot be checked here at all — two macro expansions cannot see each other — so each storage macro mints the same marker item in the declaring scope and two of them are E0428 at the offending type. tests/storages/ reads the collision back.

§THE RECORD FAMILY IS A LADDER, and each word names what its rung HAS

tierwordhaslacks
field fragment[fields]shared fields, declared once, inherited by holdersidentity, rows, wire root
entityentityid · key · lineage · accessors · filter and comparison faces · a wire facerows
recordrecordeverything above plus the storage essence — rows, in the databases it names—

[fields] is beside the node family rather than in it: a fragment is HELD, so it is not a node at all — no identity, no storage, no wire root, and therefore no marker and no place in the one-storage law above. The word used to be entity, and the tier’s own doc confessed the mismatch in as many words (no stable identity is what the tier means) while entity means an identity-bearing thing everywhere else in this framework — the entity binding, a hit’s entity field, TypedId’s entity marker. So the word moved up to the rung it always described.

record and entity differ in the STORAGE ESSENCE and in nothing else, which is why a record names its stores BARE at the head — #[ingraph::record(sqlite, postgres)] — rather than inside a wrapper. An optional axis gets a block (graphql(…)); an essence never wraps. A record naming no store is refused and told the two exits, because a record IS rows.

Every expansion may use only ingraph’s public API, so a hand-written declaration and a generated one are the same program. The design is recorded in docs/ (not published).

§AN EXPANSION ASSUMES THE FRAMEWORK’S TIERS ARE IN PLACE

ingraph is cut into tiers — a vocabulary core, then engine, then runtime, then derive — and what these macros write reaches into all of them. A declaration’s expansion names __private::drive, __private::source, __private::operator, __private::resource and __private::retrieve, and it names them as ABSOLUTE paths carrying no #[cfg], because a #[cfg(feature = …)] written inside an expansion asks whether the DECLARING crate has a feature by that name rather than whether ingraph was built with one.

So the assumption is not a convention this crate could relax — it is what makes an emitted path resolve at all, and ingraph’s own feature table states it as derive = […, "runtime"]. A consumer taking the attributes as ingraph::record inherits the tiers with the word.

A consumer taking them as ingraph_derive::record — which is this crate’s own fixture corpus, and the form a test uses when the MACRO rather than the re-export is its subject — is outside that implication and names runtime on its own ingraph dependency. Without it an expansion is E0433 at the first shelf path it writes, which is a resolution failure rather than a missing impl.

Below the derives sits a small PARSING LAYER the whole crate shares — [errors] for reporting every violation rather than the first, [attribute] for the #[ingraph(…)] grammar’s structure, [value] for typed option values, column for what an emitted column may be called. None of it knows what a record is; Record is its first consumer, and the derives that follow are why it is separate.

The crate is a SHELL: [parse] turns the compiler’s tokens into an RecordModel and checks every rule, and ingraph-codegen turns that model back into tokens. Neither half needs the other’s machinery, which is what lets a manifest reach the same emitter later.

Attribute Macros§

aggregate
Declare an AGGREGATE — a record whose rows are a declared FOLD over one upstream’s rows, one row per group, recomputed WHOLE on every trigger.
blob
Declare an ARTIFACT FAMILY derived from another node’s messages — an operator holding one stored object per message it saw.
entity
Declare an ENTITY — an identity-bearing node with a wire face and NO rows.
fields
Declare a FIELD FRAGMENT — a group of fields several declarations hold, written once.
flags
Declare a FLAGS SET — a closed vocabulary of BITS a column holds a SUBSET of.
fulltext
Declare a FULL-TEXT INDEX over another node’s messages — an operator holding one document per message it saw, searchable by text.
graph
Declare a GRAPH ROOT — the struct whose fields are an application’s nodes.
interface
Declare an INTERFACE — a member set with a contract over it.
journal
Mount a JOURNAL — the canonical record of how far each content ROOT got through each node.
mutation
Declare a SOURCE’s COMMAND FACE — the vocabulary an application can say to one running origin.
mutation_error
Dress an application’s own failure type to RENDER — a declared exchange’s error, given a code and a sentence.
operator
Declare an OPERATOR — a graph node that subscribes, computes, emits, and owns NO storage.
query_error
mutation_error for the READ path — the same skeleton, over an author’s own query failure.
record
Declare a RECORD — an entity holding rows, in the databases its STORE WORDS name.
resource
Declare a SHAREABLE RESOURCE — a type several units may hold at once.
search
Declare a SEARCH RECIPE — the members one question is asked across, and the towers that turn it into what each of them can be asked with.
source
Declare an ORIGIN — and hold its mutation word and its type Mutation seat to each other.
tower
Declare a QUESTION PIPELINE — the steps between what a person asked and what an index can be asked with.
vector
Declare an EMBEDDING INDEX over another node’s messages — an operator holding one document per message it saw, searchable by nearness.

Derive Macros§

Comparison
Give a HAND-WRITTEN struct the COMPARISON face — one predicate type per database it names, each field the comparison its column’s filter crosses into.
Enum
Equip a VOCABULARY — a unit-variant enum — with the WHOLE citizenship: the faces a column of it needs, and the face a schema needs.
Filter
Give a HAND-WRITTEN struct the FILTER face a record’s declaration gets — a predicate over its fields, each field its type’s filter.
Id
Equip an ID WRAPPER — a #[repr(transparent)] type holding one value — with the whole register an address needs.
NewType
Equip a NEWTYPE — a type this crate declares that wraps ONE value — with the faces it names.
OrderBy
Give a HAND-WRITTEN struct the ORDER-BY face — one term per field, each carrying the direction it runs in, plus the two questions every term answers.
Union
Equip a DECLARED UNION — an enum whose every variant carries one member type.