docs: events now optional — Status headers + conditional HTML rendering

- ADR-015: Status → Optional with scaffold command + behavior note (bus absent
  means no-op, IJobQueue unaffected)
- events-and-jobs.md: prerequisite callout block explaining core-events is
  optional, how to scaffold, and which features require it
- data-flow-explainer.html: note bus is optional in BindProductionContext blurb;
  add inline comment in code snippet that bus is scaffoldable

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-09 14:01:38 +02:00
parent a9f27f0d7e
commit 3d653666c2
3 changed files with 20 additions and 2 deletions

View File

@@ -1703,6 +1703,7 @@ footer .colophon {
<h3>blog/di/<em>bind-production.ts</em></h3>
<p>Called from each app's bootstrap (<code>apps/web-next/src/server/bind-production.ts</code>) with the <code>ctx</code> object built once by the aggregator. <code>BindProductionContext</code> is imported from <code>@repo/core-shared/di</code>.</p>
<pre class="code" data-lang="typescript // packages/blog/src/di/bind-production.ts"><span class="k">export function</span> <span class="n">bindProductionBlog</span>(<span class="n">ctx</span>: <span class="t">BindProductionContext</span>): <span class="t">void</span> {
<span class="c">// bus is optional — present only when @repo/core-events is scaffolded</span>
<span class="k">const</span> { <span class="n">config</span>, <span class="n">tracer</span>, <span class="n">logger</span>, <span class="n">bus</span>, <span class="n">queue</span>, <span class="n">realtime</span>, <span class="n">realtimeRegistry</span> } = <span class="n">ctx</span>;
<span class="k">if</span> (<span class="n">blogContainer</span>.<span class="n">isBound</span>(<span class="n">BLOG_SYMBOLS</span>.<span class="n">IArticlesRepository</span>)) {
<span class="n">blogContainer</span>.<span class="n">unbind</span>(<span class="n">BLOG_SYMBOLS</span>.<span class="n">IArticlesRepository</span>);
@@ -2192,7 +2193,7 @@ footer .colophon {
<div class="tradeoff-card">
<div class="tag">di/bind-production.ts</div>
<h3>Production binder</h3>
<p class="blurb"><code>bindProduction&lt;F&gt;(ctx: BindProductionContext)</code> — unbinds the mock, rebinds the real Payload-backed impl. The <code>ctx</code> arg carries required fields (<code>tracer</code>, <code>logger</code>, <code>config</code>) and optional cross-cutting deps (<code>bus</code>, <code>queue</code>). Realtime deps (<code>realtime</code>, <code>realtimeRegistry</code>) are also optional — present only when <code>@repo/core-realtime</code> is scaffolded via <code>pnpm turbo gen core-package realtime</code>.</p>
<p class="blurb"><code>bindProduction&lt;F&gt;(ctx: BindProductionContext)</code> — unbinds the mock, rebinds the real Payload-backed impl. The <code>ctx</code> arg carries required fields (<code>tracer</code>, <code>logger</code>, <code>config</code>) and optional cross-cutting deps (<code>queue</code>). Event bus (<code>bus</code>) is also optional — present only when <code>@repo/core-events</code> is scaffolded via <code>pnpm turbo gen core-package events</code>; absent, <code>bus?.subscribe/publish</code> calls are no-ops. Realtime deps (<code>realtime</code>, <code>realtimeRegistry</code>) are also optional — present only when <code>@repo/core-realtime</code> is scaffolded via <code>pnpm turbo gen core-package realtime</code>.</p>
<div class="pc-cols">
<div class="pros"><h5>Pros</h5><ul>
<li>Decouples Payload config from the feature package — boundary stays clean</li>