Skip to main content

ingraph_codegen/
lib.rs

1#![deny(missing_docs)]
2// The docs.rs badge half: `doc_cfg` derives the "Available on crate feature `x` only" banner from
3// the `cfg` a gated item already carries. This crate declares NO features, so it derives nothing
4// today — the attribute is here because the knob that turns it on is, and the two belong together:
5// `docsrs` is set by the `rustdoc-args` in `[package.metadata.docs.rs]` below and by nothing else,
6// so a root that never named `doc_cfg` would leave that cfg dangling. Nightly-only, hence the
7// `cfg_attr`; every stable build compiles a crate that has never heard of `docsrs`.
8#![cfg_attr(docsrs, feature(doc_cfg))]
9//! The emission engine behind [`ingraph-derive`](https://docs.rs/ingraph-derive).
10//!
11//! Model in, tokens out. Nothing here parses: [`model::RecordModel`] is a plain struct with public
12//! fields, so the two front ends that will ever build one — the derive today, `ingraph-compiler`
13//! from a manifest later — reach the SAME emitter without either of them being this crate's
14//! concern. Validation belongs with those front ends, which hold the source spans to report at.
15//!
16//! The manifest is not this crate's, despite what an earlier draft of this doc said: under the
17//! settled architecture a manifest and a GraphQL schema are compiled by `ingraph-compiler` into
18//! the decorated declarations these macros expand. This crate is the last step of that pipeline,
19//! and the whole of it for a hand-written record.
20//!
21//! # WHAT THE TOKENS ASSUME ABOUT `ingraph`'s TIERS
22//!
23//! `ingraph` is cut into tiers — a vocabulary core, then `engine`, then `runtime`, then `derive` —
24//! and this crate emits `__private::drive`, `__private::source`, `__private::operator`,
25//! `__private::resource` and `__private::retrieve` freely, because the tiers behind those shelf
26//! segments are IMPLIED by the feature that supplies the words a declaration is written in. The
27//! emitter therefore writes no tier gate at all, and there is no `if_runtime!` to write one with.
28//!
29//! That is a fact about the framework's feature table rather than a promise this crate makes, and
30//! it is what keeps the emitter free of a decision it could not express anyway: a `#[cfg]` written
31//! into emitted tokens is evaluated in the DECLARING crate, so it asks a question about somebody
32//! else's manifest. The gate family in `ingraph::gate` exists for exactly the conditions that
33//! cannot be settled here; the tiers are not among them, because they are settled by implication
34//! before an expansion is ever reached.
35
36pub mod aggregate;
37pub mod alias;
38pub mod catalog;
39/// The COMPOSED MODE's model — the wire face of a filter struct somebody wrote by hand, built out
40/// of its own fields.
41pub mod composed;
42/// THE CONSTRUCTION PROTOCOL's model — the sequence of calls a wrapped type is built by, and the
43/// writer that spells one.
44pub mod construct;
45pub mod cron;
46pub mod delegate;
47pub mod duration;
48/// The ELEMENT MODE's model — a declared element's own filter, and the citizenship it needs.
49pub mod element;
50pub mod emit;
51/// WHERE an elected field is written — the engine blocks, and the `(field × engine)` slots they are.
52pub mod engine;
53pub mod enumeration;
54/// The LEAF ERROR's model — an application's own failure type, dressed to render under its code.
55pub mod error;
56pub mod extension;
57/// The FIELD-FRAGMENT TIER's model — the fields a holder inherits, and the width they occupy.
58pub mod fields;
59pub mod flags;
60/// THE FUSION TREE's own emission — the leaf and tier packages a declaration mints, and the
61/// `Fusable` impl a parent absorbs them through.
62pub mod fuse;
63pub mod graph;
64/// THE ID DEVICE's model — the register a `#[repr(transparent)]` id wrapper is equipped
65/// with, from the sealed vocabulary's transparency row out to the schema's own scalar.
66pub mod id;
67pub mod index;
68pub mod interface;
69pub mod journal;
70pub mod launch;
71pub mod method;
72pub mod model;
73/// THE MUTATION NODE's model — the command vocabulary a source is controlled through, and the
74/// record a source's own expansion reads that declaration through.
75pub mod mutation;
76pub mod name;
77/// THE NEWTYPE DEVICE's model — the kits a declared wrapper opts into, and the pass-through row
78/// each one installs.
79pub mod newtype;
80pub mod options;
81pub mod plural;
82/// THE EMISSION PREFIX — the mark every name this crate mints into a declaration's own scope
83/// wears, and the seat a domain framework building these models sets to its own.
84pub mod prefix;
85pub mod remote;
86pub mod resource;
87/// THE SEARCH RECIPE's model — the members a recipe fuses, the towers bound to them, and the seats
88/// one broadcast question is filled at.
89pub mod search;
90/// THE ORIGIN's model — the double entry a source declaration writes between its `mutation` word and
91/// the `type Mutation` seat its author's own `impl` fills.
92pub mod source;
93/// The STANDALONE family's model — a hand-written struct's three faces, composed from the units.
94pub mod standalone;
95/// THE TOWER's model — a question pipeline's two ends, its steps, and the chain the emission
96/// demands between them.
97pub mod tower;
98pub mod union;
99/// The FACTORED UNITS the grammar words compose and the standalone derives are the bare doors of.
100pub mod unit;
101
102/// Everything a front end needs, in one `use`.
103pub mod prelude {
104  pub use crate::{
105    alias::{ALIAS_PREFIX, DEPTH_CEILING},
106    construct::{Blanket, Build, Construction, Cross, Injection, Seat},
107    delegate::{Delegate, DelegateSkin},
108    emit::PAIRED,
109    engine::{Engine, EngineKind, FieldEngines, Slot},
110    // `index::Upstream` is NOT among these, and the one-word rename is why. `source` → `upstream`
111    // gave both grammars the same word, so this crate now holds two `Upstream` structs: the
112    // record's (`model::Upstream`, one `upstream(…)` entry inside `subscribe(…)`) and the index
113    // family's (`index::Upstream`, the `upstream(node = …, <field> = …)` block). A prelude can
114    // carry one of them unqualified. It carries the record's, which every front-end path names;
115    // the index one has a single consumer and that consumer already spells `index::Upstream`.
116    index::{IndexModel, Projected},
117    journal::JournalModel,
118    method::{ColumnOrigin, Emitted, Member, Origin, Owner},
119    model::{
120      AliasOptions, Artifact, ArtifactBytes, AsyncGraphql, BackendError, ChangesFeed,
121      ChannelOptions, Column, CompositeUnique, Condition, Conversion, Crossing, DatabaseBackend,
122      DatabaseKind, Declared, Derived, Face, FallibleConversion, FanIn, Field, Fill, Filled,
123      FrameworkMarker, Fusion, Grant, Grants, Graphql, GraphqlBackend, GraphqlField, GraphqlKind,
124      Key, Kind, Label, Lineage, Marker, Mirror, MongoDatabase, MySqlDatabase, NodeKind, Persist,
125      PersistColumn, PollBody, PollCadence, PollEntry, PollMode, Polls, PostgresDatabase,
126      PostgresProgress, Product, Products, Progress, ProgressHost, Projection, RecordModel,
127      Reference, Role, Shape, SqliteDatabase, SqliteProgress, Storage, Subscription, Through,
128      TracingLevel, Upstream, Upstreams, WireLeg, WirePosition, borrowed_key,
129      default_channels_name, default_comparison_name, default_downstream_name, default_due_name,
130      default_filter_name, default_in_name, default_input_name, default_key_name,
131      default_key_output_name, default_lineage_name, default_order_by_name, default_out_kind_name,
132      default_out_name, default_output_name, default_polling_name, default_row_name,
133      default_sweeps_name, fanned_lineage, fanned_lineage_column, one_storage_marker,
134      poll_grants_name, shelf_name,
135    },
136    name::RustSafeName,
137    prefix::EmissionPrefix,
138  };
139}
140
141#[cfg(test)]
142mod tests;