1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
use *;
/// A NULLABLE column's filter: `F`'s operators, plus the null test — which exists here and in no
/// other filter type.
///
/// Nullability is a fact about the COLUMN, so it is carried by the type. A bare `T` resolves to its
/// plain filter and an `Option<T>` to this wrapper — one blanket over every `T`, since a nullable
/// column has exactly one reading whatever it wraps — which is what makes `IS NULL` against a
/// `NOT NULL` column unrepresentable rather than merely unsatisfiable. The
/// predecessor put an `is_null` slot on all six kinds and registered `T` and `Option<T>` to the SAME
/// filter, so a client could ask a `NOT NULL` column whether it was null and get an empty result set —
/// a query that cannot match reported as a query that matched nothing, which an agentic consumer has
/// no way to tell apart from an honest miss.
///
/// One wrapper rather than a nullable TWIN per kind: twins are an M×N over the kinds, and a
/// generic default (`BytesFilter<B, K = Variable>`) would then be declared in two places, free to
/// drift apart. Named for what it modifies — `Nullable<ScalarFilter<i64>>` reads as the modifier it
/// is, where `NullableScalarFilter<i64>` stutters.
///
/// # The guarantee, as the compiler sees it
///
/// A nullable column's filter takes the null test:
///
/// ```
/// use ingraph::{DefaultMarker, GraphqlFilter, Nullable, ScalarFilter, ToGraphqlFilter};
///
/// // What an expansion writes for a field of type `T`.
/// type Column<T> = <<T as DefaultMarker>::Marker as ToGraphqlFilter>::Filter;
///
/// // `Option<u32>` is a NULLABLE column, and this is the type it resolves to.
/// let f: Column<Option<u32>> = Nullable::new(ScalarFilter::new().with_eq(1)).with_null(false);
/// assert!(!f.is_empty());
/// ```
///
/// A `NOT NULL` column's does not — there is no such operator on the type at all (`E0599`):
///
/// ```compile_fail,E0599
/// use ingraph::{DefaultMarker, GraphqlFilter, Nullable, ScalarFilter, ToGraphqlFilter};
///
/// type Column<T> = <<T as DefaultMarker>::Marker as ToGraphqlFilter>::Filter;
///
/// // Bare `u32` is a `NOT NULL` column, and this is the type it resolves to.
/// let f: Column<u32> = ScalarFilter::new().with_eq(1);
/// let _ = f.with_null(false);
/// ```
///
/// The two earn their keep only together. Stable rustdoc runs a `compile_fail` block just far enough
/// to see it fail and never checks WHY, so the negative one alone would still "pass" with the imports
/// gone stale; the positive twin shares those imports and that `with_eq` call and must COMPILE. And
/// they fail in opposite directions: pointing the `Option` blanket back at the bare filter reds the
/// FIRST block, while giving a bare `T` the wrapper reds the SECOND.
///
/// # No `Deref` to `F`
///
/// The inner filter is reached through [`inner`](Self::inner), and it answers about ITS operators
/// alone. A whole-filter question must account for the null slot too: [`is_empty`](Self::is_empty)
/// does, and [`ScalarFilter::is_referential`] — asked on the inner filter — does not. That is why
/// there is no transparent access: a nullable foreign key has no `is_referential` to call, so it
/// cannot collapse onto the parent column, and `inner().is_referential()` is visibly a question about
/// the inner filter rather than about this one.
/// The bound's row, and the ONE that reaches for a second: this wrapper's own `try_map` takes the
/// inner FILTER, so an OPERAND converter reaches the operands only by asking the wrapped kind for
/// its row too. That is the nested call `try_map`'s note spells out, written once here.
/// The row this whole trait exists for, and the one that makes its parameter mean one thing: a
/// column DECLARED at `Option<T>` is equated to an `Option<T>`.
///
/// `EqualsFilter<T>` reads *the filter for a column declared at `T`* at every row, and this wrapper
/// is what a declared `Option` resolves to — so the operand carries the same `Option` the
/// declaration wrote, and an emitter holding a column's type holds its operand's type too. The
/// alternative, taking a bare `T` here, would make the parameter mean the DECLARED type at eight
/// rows and the wrapped one at the ninth, and a type-blind caller could no longer name it.
///
/// The two arms are the two things such a column can be asked, and both are what a declaration can
/// spell:
///
/// * `Some(v)` — the wrapped kind's equality, with the null test unset. `IS NULL` is a question
/// about the COLUMN rather than about a value, so equating one never answers it, and an arm that
/// also wrote `null: Some(false)` would drop the rows a caller asked for by a predicate nobody
/// wrote.
/// * `None` — the null test alone, over `F`'s empty filter: *this column IS null*, which is the
/// only reading an absent operand has on a column that can hold one.
/// A bare filter face taken apart into the two pieces its NULLABLE twin is assembled from — the
/// DELEGATION TRAIT that makes [`Nullable<F>`]'s wire face ONE blanket row.
///
/// # The wall this is the door through
///
/// `Nullable` is this crate's type and `async_graphql::InputType` is async-graphql's, so a
/// DECLARING crate cannot write `impl InputType for Nullable<TimebaseFilter>`: `E0117`, RFC 2451
/// admitting no `ForeignTrait for ForeignType<Local>`. This crate cannot write it either, never
/// having heard of `TimebaseFilter`. An `Option<Timebase>` column was therefore unspellable on the
/// wire whatever either side did — the hole `ingraph-codegen`'s element mode recorded and routed
/// around by aliasing its enum family onto a framework type.
///
/// What blocked the obvious fix was `E0119`: one generic `impl<F> InputType for Nullable<F>` here
/// overlapped the concrete `Nullable<ScalarFilter<i64>>` rows the registrations minted. So the rows
/// moved onto THIS trait — every one of them, which is what leaves the generic impl unopposed. It is
/// exactly the move [`TextWire`](crate::TextWire) made for `TextFilter`'s own face, one type over: a
/// per-instantiation table becomes a delegation a downstream crate can join, because the impl it
/// writes names a LOCAL self type.
///
/// # What a row supplies, and what it does NOT
///
/// The twin is FLAT — the bare face's fields beside `isNull` in one input object — and its whole
/// remaining behaviour is derivable from the bare face:
///
/// * the NAME is `Nullable` before the bare face's own, written once in the blanket so a row cannot
/// disagree with it;
/// * `parse` reads `isNull` off the object and hands the SAME object to `Self::parse`, which reads
/// its keys by name and ignores every other — so the operator slots keep exactly one parser;
/// * the SHORTHAND LAW's rule ② lands there and only there, over `Self::default()`.
///
/// That leaves the two pieces a bare face keeps to itself, because both are built INSIDE
/// `create_type_info`'s registry closure and `to_value`'s body where nothing can reach them.
///
/// # `Default` and `InputType` sit on the seat
///
/// Both are structural rather than incidental. The null-test-alone state is `Self::default()` under
/// the wrapper, and every other arm delegates to `Self::parse` — so a row missing either could not
/// be spent at all, and stating them here makes that `E0277` at the row a reader can go and fix
/// instead of an unsatisfied blanket at a use site far away.
/// The ONE wire face every nullable column wears, and the row the delegation trait was minted for.
///
/// Its name is `Nullable` before the wrapped face's own, computed HERE rather than declared by the
/// row: the modifier prefix is the framework's naming law, and a second literal at each row would be
/// free to disagree with the name that row already publishes.