Skip to content

Commit 5df9f20

Browse files
authored
Merge pull request #238 from taras/feat/content-failure-boundary
✨ Make content() the failure boundary for function components
2 parents 31a6b7d + bca77a2 commit 5df9f20

16 files changed

Lines changed: 2077 additions & 180 deletions

‎packages/core/mod.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ export type { EvalEnv } from "./src/types.ts";
7070
export { compileBlock } from "./src/eval-context.ts";
7171

7272
export { hasContent, useContent } from "./src/content-context.ts";
73+
export { ContentError } from "./src/errors.ts";
7374
export { InvocationTeardownError, withInvocation } from "./src/invocation.ts";
7475
export type { Invocation } from "./src/invocation.ts";
7576
export { Sample } from "./src/sample-api.ts";

‎packages/core/src/component-api.ts‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,24 @@ export interface ComponentApi {
100100
codeBlock(): Operation<CodeBlockContext>;
101101
/** Whether the current block runs with persistent resource lifetime. */
102102
persistent: boolean;
103-
/** Render the invoking component's children (optionally a named slot). */
103+
/**
104+
* Render the content the invoking component was written with — the default
105+
* content, or a named slot (spec §5.1.2). This is the canonical operation for
106+
* a function component; `useContent(slot?)` is a compatibility alias for it.
107+
*
108+
* Each call is a failure boundary. Requested content that expands cleanly
109+
* comes back as its rendered string. Requested content that produces
110+
* ErrorSegments throws `ContentError` carrying those original segments, so
111+
* normal continuation stops at the `yield* content()` expression: the
112+
* component's return is not processed and no `as` binding is made. Left
113+
* uncaught, the invocation is replaced by the original errors under a
114+
* collecting policy, or the original `DocumentationError` is restored under a
115+
* throwing one.
116+
*
117+
* Catching `ContentError` around the call is explicit recovery — the
118+
* component chooses what to render instead, and its consumer never sees the
119+
* failure. Only content the component asks for is expanded.
120+
*/
104121
content(slot?: string): Operation<string>;
105122
/** Whether the invoking element was written with content rather than self-closed. */
106123
hasContent(): Operation<boolean>;
@@ -165,6 +182,11 @@ export const Component: Api<ComponentApi> = createApi<ComponentApi>("Component",
165182
);
166183
},
167184
persistent: false,
185+
/**
186+
* Calling for content outside an invocation is a mistake in the caller, not a
187+
* content failure, so this is an ordinary Error: a component's
188+
* `catch (error) { if (error instanceof ContentError) … }` does not absorb it.
189+
*/
168190
// deno-lint-ignore require-yield
169191
*content(_slot?: string): Operation<string> {
170192
throw new Error(

‎packages/core/src/components/File.ts‎

Lines changed: 35 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,9 @@ import {
7171
stat,
7272
writeTextFile,
7373
} from "@executablemd/runtime";
74-
import { Component } from "../component-api.ts";
75-
import { hasContent, useContent } from "../content-context.ts";
74+
import { content } from "../component-api.ts";
75+
import { hasContent } from "../content-context.ts";
76+
import { ContentError } from "../errors.ts";
7677
import type { Json } from "../types.ts";
7778
import { reason } from "./fs-diagnostics.ts";
7879

@@ -87,8 +88,8 @@ export const props = {
8788

8889
/** A path that leaves the working directory, or a target that cannot be text. */
8990
export class FileAccessError extends Error {
90-
constructor(message: string) {
91-
super(message);
91+
constructor(message: string, options?: ErrorOptions) {
92+
super(message, options);
9293
this.name = "FileAccessError";
9394
}
9495
}
@@ -126,7 +127,7 @@ export default function* (props: Record<string, Json>): Operation<string> {
126127
if (yield* hasContent()) {
127128
// The children run only once the path is known to be usable, and the
128129
// destination is resolved only once they are done.
129-
const text = yield* content(requested);
130+
const text = yield* rendered(requested);
130131
yield* write(requested, yield* destination(admitted), text);
131132
return "";
132133
}
@@ -137,34 +138,38 @@ export default function* (props: Record<string, Json>): Operation<string> {
137138
/**
138139
* The rendered children, or a failure if anything went wrong producing them.
139140
*
140-
* A code block that fails is a diagnostic under a collecting policy: the
141-
* children still render, with the diagnostic embedded in the text. For a
142-
* component that renders its content that is right — the reader sees what
143-
* failed, in place. A write has nowhere to show it, and writing the diagnostic
144-
* into the file would be worse than useless, so this watches for one being
145-
* raised and turns the whole invocation into a failure instead. Nothing
146-
* reaches the filesystem, and the target keeps whatever it already held.
141+
* `content()` is a failure boundary: content that fails to expand throws
142+
* `ContentError` there rather than coming back as text with the diagnostic
143+
* embedded in it. For a component that renders its content, embedding is the
144+
* right outcome — the reader sees what failed, in place. A write has nowhere to
145+
* show it, and writing the diagnostic into the file would be worse than
146+
* useless, so this recovers from the boundary and turns the whole invocation
147+
* into a failure instead. Nothing reaches the filesystem, and the target keeps
148+
* whatever it already held.
147149
*
148-
* The messages come along, because `<File>` renders nothing: this diagnostic
149-
* is the only place the reader would learn what actually went wrong.
150+
* The original messages come along, because `<File>` renders nothing: this
151+
* diagnostic is the only place the reader would learn what actually went wrong.
152+
* Anything else thrown is not a content failure and passes through untouched.
153+
*
154+
* The content failure itself stays in this failure's cause chain. What is
155+
* reported is this component's own diagnostic — the write is what the document
156+
* asked for, and that it did not happen is the fact a reader needs — while the
157+
* failure it was translated from, and the error segments it carries, remain
158+
* reachable underneath for a host inspecting what ended the execution.
150159
*/
151-
function* content(requested: string): Operation<string> {
152-
const failures: string[] = [];
153-
154-
yield* Component.around({
155-
*raise([error], next) {
156-
failures.push(error.message);
157-
return yield* next(error);
158-
},
159-
});
160-
161-
const rendered = yield* useContent();
162-
if (failures.length > 0) {
160+
function* rendered(requested: string): Operation<string> {
161+
try {
162+
return yield* content();
163+
} catch (error) {
164+
if (!(error instanceof ContentError)) {
165+
throw error;
166+
}
167+
const failures = error.errors.map((segment) => segment.message);
163168
throw new FileAccessError(
164169
`did not write "${requested}": its content failed to expand. ${failures.join(" ")}`,
170+
{ cause: error },
165171
);
166172
}
167-
return rendered;
168173
}
169174

170175
/** A path that has passed the lexical stage, carried to the resolving one. */
@@ -303,7 +308,7 @@ function* read(requested: string, target: string): Operation<string> {
303308
type Step = "preparation" | "commit";
304309

305310
/**
306-
* Replace `target` with exactly `content`.
311+
* Replace `target` with exactly `text`.
307312
*
308313
* The content is whole by the time this runs — the children expanded first —
309314
* so a child that failed never reaches the filesystem at all. What remains is
@@ -337,7 +342,7 @@ type Step = "preparation" | "commit";
337342
* write did rather than instead of it: both outcomes are collected here and
338343
* raised together, so neither hides the other.
339344
*/
340-
function* write(requested: string, target: string, content: string): Operation<void> {
345+
function* write(requested: string, target: string, text: string): Operation<void> {
341346
const info = yield* guard(requested, "write", stat(target));
342347
if (info.exists && !info.isFile) {
343348
throw new FileAccessError(
@@ -360,7 +365,7 @@ function* write(requested: string, target: string, content: string): Operation<v
360365
const temporary = `${target}.xmd-${randomUUID().slice(0, 8)}.tmp`;
361366
yield* ensure(() => discard(requested, temporary, uncleaned));
362367
try {
363-
yield* writeTextFile(temporary, content);
368+
yield* writeTextFile(temporary, text);
364369
step = "commit";
365370
yield* rename(temporary, target);
366371
} catch (error) {

‎packages/core/src/content-context.ts‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,28 @@
11
/**
2-
* What a function component asks about the content it was invoked with.
2+
* Compatibility aliases for what a function component asks about the content it
3+
* was invoked with.
34
*
4-
* `useContent()` is the function component equivalent of `<Content />` in
5-
* markdown components; `hasContent()` answers whether there is any to render.
6-
* Both are ergonomic aliases for Component operations the expansion engine
7-
* installs around each function component invocation.
5+
* `content(slot?)` from `component-api.ts` is the canonical operation — the
6+
* function component equivalent of `<Content />` in markdown components, and
7+
* the failure boundary for the content it renders (spec §5.1.2). `useContent()`
8+
* stays supported and delegates to it unchanged, including its `ContentError`
9+
* semantics. `hasContent()` answers whether there is any content to render.
10+
*
11+
* Both alias Component operations the expansion engine installs around each
12+
* function component invocation. The `useContent` binding injected into eval
13+
* blocks is a different, policy-carrying closure (spec §4.3), not this alias.
814
*/
915

1016
import type { Operation } from "effection";
1117
import { content, hasContent as componentHasContent } from "./component-api.ts";
1218

1319
/**
14-
* Render children content from the invoking component.
20+
* Render the invoking component's content — the compatibility alias for
21+
* `content(slot?)`, which new components import directly.
22+
*
23+
* Behaves identically: the requested content comes back as a rendered string,
24+
* and content that fails to expand throws `ContentError` at this call rather
25+
* than returning (spec §5.1.2).
1526
*
1627
* @param slotName - Optional slot name. If provided, renders only the
1728
* content assigned to that slot (matching `<Content slot="name" />`).

0 commit comments

Comments
 (0)