Skip to content

Commit 0fa1294

Browse files
authored
✨ Leave out a prop whose expression produced nothing (#537) (#541)
An ordinary component's expression prop that evaluates successfully to `undefined` is now absent rather than rejected: the omission happens in the one resolver both Markdown and function components pass through, before validation, so an optional prop stays unset, a declared default applies, and a required one fails as missing with no body run. `null`, evaluation failures, non-serializable roots, nested normalization, captures and `<Let value>` are unchanged, and nothing durable holds `undefined`. The scanner keeps an ordinary component's literal `{undefined}` as an expression so it reaches that same resolver; a construct's arbitrary-value operand keeps its scan-time reading. One authored `<PullRequest number={pullRequest.number}>` inside a bounded loop now creates without a number and then updates the number it created. Co-authored-by: Taras Mankovski <[email protected]>
1 parent d8e136e commit 0fa1294

10 files changed

Lines changed: 477 additions & 45 deletions

File tree

‎architecture.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2648,6 +2648,35 @@ owner keeps; both are absent from every key list, descriptor, and copy. A
26482648
capability boundary that a handler holding the object could read across is not
26492649
one, whichever of the two properties it was reasoned from.
26502650

2651+
## The ordinary component prop boundary
2652+
2653+
An ordinary component's props are JSON, and one resolver decides that for both
2654+
Markdown and function components — before validation, and before anything
2655+
durable is written.
2656+
2657+
- **A successful `undefined` means the prop is absent.** The resolver leaves it
2658+
out rather than giving it a value, so the schema answers it: an optional prop
2659+
stays unset, a declared default is supplied, and a required one fails as a
2660+
missing property with no body run. That is how one authored invocation can
2661+
carry an optional identity a preceding result supplies later.
2662+
- **`null` is a value the author wrote.** It crosses the boundary as itself, and
2663+
only a schema that accepts it accepts it. Absence is never widened to it, and
2664+
never widened to a root a JSON round trip cannot describe: a function, a
2665+
symbol and a serialization that threw stay the failure they were, as do an
2666+
expression that threw and a name that is not bound.
2667+
- **The rule stops at the root.** Everything under it is the same native
2668+
`JSON.stringify` round trip as before — an `undefined` object member is
2669+
dropped, an `undefined` array entry becomes `null` — and no recursive
2670+
normalizer of ours replaces it.
2671+
- **Deliberate bypasses stay bypasses.** A capture is separated before this
2672+
resolver runs and receives the exact operand, `undefined` included; `<Let
2673+
value>` binds by reference; a construct that evaluates an arbitrary operand
2674+
keeps its own contract.
2675+
- **Absence is not durable state.** Prop resolution records nothing of its own.
2676+
No resolved prop, validated prop, retained event or replay-restored prop holds
2677+
`undefined`, and a replay reconstructs the same validated prop set through
2678+
ordinary expansion.
2679+
26512680
## Construct inventory
26522681

26532682
Status is measured against main.

‎packages/core/src/expand.ts‎

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2683,10 +2683,10 @@ function* expandFunctionComponent(
26832683
// The scanner resolved this one because its text reads as JSON, but the
26842684
// definition that was selected declares it a capture — so the reading is
26852685
// not what the author asked for. Evaluating the authored text is: it is
2686-
// the same expression, run where the by-reference contract holds, and it
2687-
// is the only way `value={undefined}` reaches a component as `undefined`
2688-
// rather than as `null`. A prop written as a quoted attribute has no
2689-
// authored expression and stays the literal string it was.
2686+
// the same expression, run where the by-reference contract holds, so a
2687+
// value JSON has no shape for reaches the component as itself. A prop
2688+
// written as a quoted attribute has no authored expression and stays the
2689+
// literal string it was.
26902690
const authored = authoredExpressions[key];
26912691
if (authored === undefined) {
26922692
literalCaptures[key] = value;
@@ -3153,7 +3153,17 @@ function* resolveExpressionProps(
31533153
for (const [propName, expression] of Object.entries(expressions)) {
31543154
const result = evaluateIn(evalEnv, expression, componentName, propName);
31553155

3156-
if (typeof result === "function" || typeof result === "undefined") {
3156+
// A successful `undefined` is the absence of a value, and absence is
3157+
// written by leaving the prop out (§6.5). It happens here, before
3158+
// validation, so an optional prop stays unset, a declared default is
3159+
// supplied by the schema, and a required one fails as missing — and no
3160+
// prop, event or journal value ever holds `undefined`. `null` is a value
3161+
// the author wrote and crosses the boundary as itself.
3162+
if (typeof result === "undefined") {
3163+
continue;
3164+
}
3165+
3166+
if (typeof result === "function") {
31573167
throw new Error(
31583168
`Expression prop "${propName}" on <${componentName} /> evaluated ` +
31593169
`to a non-serializable value (${typeof result}). Props must be ` +

‎packages/core/src/scanner.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
import { Err, Ok } from "effection";
1313
import type { Result } from "effection";
1414
import { validateBindingName } from "./live-env.ts";
15-
import { bindsByReference } from "./structural.ts";
15+
import { bindsByReference, isStructural } from "./structural.ts";
1616
import type {
1717
Segment,
1818
TextSegment,
@@ -623,6 +623,14 @@ function parseAttributes(
623623
const exprText = text.slice(pos + 1, exprEnd).trim();
624624
if (bindsByReference(componentName, attrName)) {
625625
expressions[attrName] = exprText;
626+
} else if (exprText === "undefined" && !isStructural(componentName)) {
627+
// An ordinary component's prop is absent when its expression produces
628+
// `undefined`, and the resolver that crosses the JSON boundary at
629+
// expansion is where that is decided (§6.5). Reading the literal here
630+
// would answer with `null` before the prop ever reaches it. A construct
631+
// evaluates its own operand under its own contract, so what it is
632+
// handed at scan time is unchanged.
633+
expressions[attrName] = exprText;
626634
} else {
627635
const result = parseExpressionValue(exprText);
628636
if (result.kind === "resolved") {
@@ -783,7 +791,10 @@ export function parseExpressionValue(expr: string): ExpressionResult {
783791
return { kind: "resolved", value: false };
784792
}
785793

786-
// null/undefined
794+
// `null` is JSON. A literal `undefined` reads as `null` here for a construct
795+
// that takes an arbitrary operand and is asked for a scan-time reading of it;
796+
// an ordinary component's is kept as an expression by the caller, because
797+
// absence is what it means there.
787798
if (trimmed === "null" || trimmed === "undefined") {
788799
return { kind: "resolved", value: null };
789800
}

‎packages/core/src/types.ts‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,9 +40,8 @@ export interface ComponentElement {
4040
*
4141
* Scanning happens before a name resolves, so the scanner cannot know
4242
* whether the definition that will run declares the prop a capture. Reading
43-
* the text as JSON is a projection — `undefined` becomes `null`, and a
44-
* function, a class instance or a cycle has no JSON shape at all — and a
45-
* capture exists precisely to avoid one. Keeping the authored text beside
43+
* the text as JSON is a projection — a function, a class instance or a cycle
44+
* has no JSON shape at all — and a capture exists precisely to avoid one. Keeping the authored text beside
4645
* the projection lets expansion, which does know the selected definition,
4746
* hand a captured prop the exact value its expression produced and every
4847
* other prop the reading it has always had (§6.5).

‎packages/core/tests/capture-props.test.ts‎

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ describe("Tier CP — capture props", () => {
6767
expect(seen.expected).toBe(re);
6868
});
6969

70-
it("CP8: a capture is the authored expression, even when it reads as JSON", function* () {
70+
it("CP8: a capture takes the operand an ordinary prop omits", function* () {
7171
const seen: Record<string, unknown> = {};
7272
const capturing: FunctionComponentDefinition = {
7373
kind: "function",
@@ -85,7 +85,8 @@ describe("Tier CP — capture props", () => {
8585
props: { type: "object", properties: { probe: {} }, additionalProperties: false },
8686
// deno-lint-ignore require-yield
8787
*fn(props): Operation<unknown> {
88-
seen.ordinary = props.probe;
88+
seen.ordinaryRan = true;
89+
seen.ordinaryHasProbe = Object.hasOwn(props, "probe");
8990
return "";
9091
},
9192
};
@@ -118,14 +119,14 @@ describe("Tier CP — capture props", () => {
118119
);
119120
});
120121

121-
// `undefined` is a JSON literal the scanner can read, and reading it is a
122-
// projection: it becomes `null`. The capture is delivered from the authored
123-
// expression instead, so the component gets what the author wrote.
122+
// A capture is handed the value its expression produced, `undefined`
123+
// included: it crosses no JSON boundary at all.
124124
expect(seen.captured).toBe(undefined);
125125
expect("captured" in seen).toBe(true);
126-
// The very same authored text on an ordinary prop keeps the reading it has
127-
// always had. The widening is per-prop, decided by the selected definition.
128-
expect(seen.ordinary).toBe(null);
126+
// The very same authored text on an ordinary prop means absence. The body
127+
// runs, and the prop is not among the ones it was given (§6.5).
128+
expect(seen.ordinaryRan).toBe(true);
129+
expect(seen.ordinaryHasProbe).toBe(false);
129130
});
130131

131132
it("CP2: a return binds by reference under `as`, and renders nothing without it", function* () {
@@ -267,7 +268,7 @@ describe("Tier CP — capture props", () => {
267268
};
268269

269270
yield* scoped(function* () {
270-
const env: EvalEnv = { values: { nothing: undefined } };
271+
const env: EvalEnv = { values: { notJson: () => 1 } };
271272
yield* Component.around({ env: () => env }, { at: "min" });
272273
yield* Component.around({
273274
*raise([segment], next) {
@@ -284,7 +285,7 @@ describe("Tier CP — capture props", () => {
284285
},
285286
{ at: "min" },
286287
);
287-
yield* expandSegments(scanSegments("<Ordinary n={nothing} />\n"), {}, {}, new Set());
288+
yield* expandSegments(scanSegments("<Ordinary n={notJson} />\n"), {}, {}, new Set());
288289
});
289290

290291
// Undeclared as a capture, so it still meets the gate that rejects a

‎packages/core/tests/component-registration.test.ts‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -496,33 +496,35 @@ describe("Tier CR — what a document gets", () => {
496496
// The capture belongs to the definition that was selected, not to the name.
497497
// An override is an ordinary Markdown component, so its `value` crosses the
498498
// prop JSON boundary exactly as any other component's would.
499-
it("CR22c: an override keeps ordinary prop projection, capture and all", function* () {
499+
it("CR22c: an override crosses the ordinary prop boundary, absence and all", function* () {
500500
const dir = yield* useFixture();
501501
yield* writeTextFile(join(dir, "doc.md"), "<Json value={undefined} />\n");
502-
// `required` plus `type: null` is what makes this discriminating: the prop
503-
// must arrive, and must arrive as the scanner's reading. A definition
504-
// treated as capturing would strip `value` before validation, and the
505-
// required check would fail instead.
502+
// `required` is what makes this discriminating: on the ordinary boundary
503+
// this operand is an absence, so the required check is what answers it. A
504+
// definition treated as capturing would strip `value` before validation
505+
// and reach the body instead.
506506
yield* writeTextFile(
507507
join(dir, "Json.md"),
508508
[
509509
"---",
510510
"required: [value]",
511511
"props:",
512-
" value: { type: 'null' }",
512+
" value: { type: 'string' }",
513513
"---",
514514
"",
515515
"override saw the projection",
516516
].join("\n"),
517517
);
518518

519-
// Core's `<Json>` fails this exact operand as "no JSON text", because it
520-
// receives the authored `undefined`. The override receives the scanner's
521-
// JSON reading of the same text — the behavior every non-capturing
522-
// component has always had.
519+
// Core's `<Json>` fails this exact operand as "no JSON text", because its
520+
// capture is handed the authored `undefined`. The override is handed the
521+
// ordinary reading of the same text, where `undefined` means the prop is
522+
// not there — the behavior every non-capturing component has (§6.5).
523523
const rendered = yield* reportOf(() => run(dir));
524-
expect(rendered).toContain("override saw the projection");
524+
expect(rendered).toContain("value");
525+
expect(rendered).toContain("required");
525526
expect(rendered).not.toContain("no JSON text");
527+
expect(rendered).not.toContain("override saw the projection");
526528
});
527529

528530
it("CR23: a broken local component fails instead of falling back to core's", function* () {

0 commit comments

Comments
 (0)