Skip to content

Commit bca77a2

Browse files
committed
🐛 Record a thrown undefined as the contextual failure's cause
Membership in the attribution map, not comparison with undefined, decides whether a DocumentationError carries a cause: a component that throws undefined threw a value, and the failure's own cause property records it. The invocation boundary transports failures as Errors — withInvocation wraps non-Error throws with asError, which keeps the string but loses the value — so a private carrier at the function frame preserves the exact thrown value across the boundary and the diagnostic is translated from it directly. Regressions: OBS23 (raise middleware sees an own cause property holding exactly undefined inside its catch; the same failure leaves expansion) and OBS24 (collecting settles a segment and constructs no Error). The fatalCause doc comment states the actual per-kind contract instead of the absolute stays-fatal-however-wrapped claim.
1 parent 343bda6 commit bca77a2

3 files changed

Lines changed: 131 additions & 11 deletions

File tree

‎packages/core/src/errors.ts‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -76,9 +76,11 @@ export class DocumentationError extends Error {
7676
super(segment.message);
7777
this.name = "DocumentationError";
7878
this.segment = segment;
79-
const from = segmentCauses.get(segment);
80-
if (from !== undefined) {
81-
this.cause = from;
79+
// Membership, not value: a component can throw `undefined`, and that is
80+
// still the exact value this failure was translated from — the own `cause`
81+
// property records it. Only a segment with no attribution has none.
82+
if (segmentCauses.has(segment)) {
83+
this.cause = segmentCauses.get(segment);
8284
}
8385
}
8486
}
@@ -145,9 +147,15 @@ export type FatalFailure = DocumentationError | DurabilityFailure;
145147
* run: expansion that carried on would reach another durable operation, whose
146148
* own mismatch is then the one reported.
147149
*
148-
* A fatal error stays fatal however it is wrapped, so this looks through the
149-
* three ways the engine and the platform aggregate failures. It returns the
150-
* fatal error itself rather than the wrapper, which is the one worth reporting.
150+
* This looks through the three ways the engine and the platform aggregate
151+
* failures and returns the fatal error itself rather than the wrapper, which is
152+
* the one worth reporting. The two kinds travel differently: a durability
153+
* failure stays fatal through the complete cause graph, while a
154+
* `DocumentationError` remains fatal unless it crossed an explicit
155+
* `ContentError` recovery boundary — a component that recovered decided what
156+
* the document reports. An uncaught private content transport restores its
157+
* original `DocumentationError` explicitly at the function-component boundary,
158+
* not through this traversal.
151159
*
152160
* **A durability failure outranks a documentation failure**, wherever each sits
153161
* in the graph. A wrapper carries whatever failed together, in whatever order

‎packages/core/src/expand.ts‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1778,6 +1778,19 @@ function errorSegments(segments: Segment[]): ErrorSegment[] {
17781778
return segments.filter((segment) => segment.type === "error");
17791779
}
17801780

1781+
/**
1782+
* Carries a non-Error value a function component threw. The invocation
1783+
* boundary transports failures as Errors — `withInvocation` wraps anything
1784+
* else with `asError`, which keeps the string but loses the value — so the
1785+
* value rides across in this carrier and the diagnostic is translated from
1786+
* the exact value the component threw, `undefined` included.
1787+
*/
1788+
class ThrownValue extends Error {
1789+
constructor(readonly value: unknown) {
1790+
super(String(value));
1791+
}
1792+
}
1793+
17811794
/**
17821795
* Report a diagnostic built from a failure, keeping that failure reachable
17831796
* underneath whatever settlement produces.
@@ -1935,7 +1948,14 @@ function* expandFunctionComponent(
19351948
},
19361949
{ at: "min" },
19371950
);
1938-
return yield* definition.fn(validatedProps);
1951+
try {
1952+
return yield* definition.fn(validatedProps);
1953+
} catch (error) {
1954+
if (error instanceof Error) {
1955+
throw error;
1956+
}
1957+
throw new ThrownValue(error);
1958+
}
19391959
});
19401960
if (asBinding) {
19411961
const parentEnv = yield* env;
@@ -1977,17 +1997,18 @@ function* expandFunctionComponent(
19771997
if (error instanceof SchemaValidationError) {
19781998
return [yield* raise(schemaValidationErrorSegment(error, name))];
19791999
}
2000+
const from = error instanceof ThrownValue ? error.value : error;
19802001
return [
19812002
yield* raiseFrom(
19822003
{
19832004
type: "error",
19842005
message:
1985-
error instanceof Error
1986-
? `Function component ${name} error: ${error.message}`
1987-
: `Function component ${name} error: ${String(error)}`,
2006+
from instanceof Error
2007+
? `Function component ${name} error: ${from.message}`
2008+
: `Function component ${name} error: ${String(from)}`,
19882009
source: name,
19892010
},
1990-
error,
2011+
from,
19912012
),
19922013
];
19932014
}

‎packages/core/tests/error-observation.test.ts‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -588,4 +588,95 @@ describe("Tier OBS — construct error observation", () => {
588588
expect(observed).toHaveLength(1);
589589
expect(observed[0]).toBe(failure.segment);
590590
});
591+
592+
// OBS23: `throw undefined` is still a thrown value. The failure's own `cause`
593+
// property records it — membership in the attribution, not comparison with
594+
// undefined, is what distinguishes "translated from undefined" from "no
595+
// attribution at all".
596+
it("OBS23: a contextual failure records a thrown undefined as its cause", function* () {
597+
const observed: ErrorSegment[] = [];
598+
const caught: Array<{ failure: DocumentationError; hasCause: boolean; cause: unknown }> = [];
599+
let thrown: unknown;
600+
601+
yield* scoped(function* () {
602+
yield* AmbientErrorPolicy.set("throw");
603+
yield* Component.around({
604+
*raise([error], next) {
605+
observed.push(error);
606+
try {
607+
return yield* next(error);
608+
} catch (failure) {
609+
if (failure instanceof DocumentationError) {
610+
caught.push({
611+
failure,
612+
hasCause: Object.hasOwn(failure, "cause"),
613+
cause: failure.cause,
614+
});
615+
}
616+
throw failure;
617+
}
618+
},
619+
});
620+
yield* Component.around(
621+
{
622+
env: () => ({ values: {} }),
623+
// deno-lint-ignore require-yield
624+
*importComponent([name], _next) {
625+
if (name !== "Boom") {
626+
throw new Error(`Component not found: ${name}`);
627+
}
628+
return throwingComponent("Boom", undefined);
629+
},
630+
},
631+
{ at: "min" },
632+
);
633+
try {
634+
yield* expandSegments(scanSegments("<Boom />"), {}, {}, new Set());
635+
} catch (error) {
636+
thrown = error;
637+
}
638+
});
639+
640+
expect(caught).toHaveLength(1);
641+
const [{ failure, hasCause, cause }] = caught;
642+
// Present and exactly undefined, already inside the middleware's catch.
643+
expect(hasCause).toBe(true);
644+
expect(cause).toBe(undefined);
645+
expect(thrown).toBe(failure);
646+
expect(observed).toHaveLength(1);
647+
expect(observed[0]).toBe(failure.segment);
648+
});
649+
650+
it("OBS24: a collected thrown undefined renders a diagnostic and produces no Error", function* () {
651+
const observed: ErrorSegment[] = [];
652+
const probe = yield* scoped(function* () {
653+
yield* Component.around({
654+
*raise([error], next) {
655+
observed.push(error);
656+
return yield* next(error);
657+
},
658+
});
659+
yield* Component.around(
660+
{
661+
env: () => ({ values: {} }),
662+
// deno-lint-ignore require-yield
663+
*importComponent([name], _next) {
664+
if (name !== "Boom") {
665+
throw new Error(`Component not found: ${name}`);
666+
}
667+
return throwingComponent("Boom", undefined);
668+
},
669+
},
670+
{ at: "min" },
671+
);
672+
const segments = yield* expandSegments(scanSegments("<Boom />TAIL"), {}, {}, new Set());
673+
return { segments, output: renderSegments(segments) };
674+
});
675+
676+
// Collecting settles a segment; no DocumentationError is ever constructed,
677+
// so there is no JavaScript Error to carry a cause.
678+
expect(observed).toHaveLength(1);
679+
expect(probe.output).toContain("Function component Boom error");
680+
expect(probe.output).toContain("TAIL");
681+
});
591682
});

0 commit comments

Comments
 (0)