@real-router/angular 0.8.0 → 0.9.0

package/ssr/functions/injectDeferred.ts

@@ -0,0 +1,92 @@
+import { computed, effect, signal } from "@angular/core";
+
+import { injectRoute } from "@real-router/angular";
+
+import type { Signal } from "@angular/core";
+
+interface DeferredContext {
+  ssrDataDeferred?: Record<string, Promise<unknown>>;
+}
+
+const NEVER_PROMISE = new Promise<never>(() => {
+  // Intentionally never resolves — settles as `undefined` indefinitely when
+  // a key is requested that the loader never declared. Surfaces consumer/
+  // loader key drift as a visible "loading" state in the UI.
+});
+
+/**
+ * Read a deferred promise published by `defer({ deferred: { <key>: Promise } })`
+ * inside an SSR data loader. Returns an Angular `Signal<T | undefined>` that
+ * tracks the active route — re-keying picks up the new state's deferred map.
+ *
+ * The signal starts `undefined` and updates to the resolved value once the
+ * promise settles. Use with native Angular control flow:
+ *
+ * ```ts
+ * @Component({
+ *   template: `
+ *     @if (reviews()) {
+ *       <ul>
+ *         @for (r of reviews(); track r.id) {
+ *           <li>{{ r.author }}</li>
+ *         }
+ *       </ul>
+ *     } @else {
+ *       <p>Loading reviews…</p>
+ *     }
+ *   `,
+ * })
+ * export class Reviews {
+ *   readonly reviews = injectDeferred<Review[]>("reviews");
+ * }
+ * ```
+ *
+ * **Asymmetric Angular** (see `.claude/SSR_FEATURE_GAPS_RU.md` §8): Angular
+ * does not ship `<Await>` / `<Streamed>` adapter components — Angular has no
+ * direct analogue to React's `use(promise)` or Svelte's `{#await}`. Use
+ * `@if (signal()) { … } @else { … }` or the `async` pipe with
+ * `from(deferredPromise)` instead.
+ */
+export function injectDeferred<T = unknown>(
+  key: string,
+): Signal<T | undefined> {
+  const { routeState } = injectRoute();
+
+  // Re-derive the promise reference whenever the route changes — invalidate()
+  // + reload, navigation to a new route, etc. all refresh the underlying
+  // deferred map, and we want the signal to track the *latest* promise.
+  const promiseSignal = computed<Promise<T>>(() => {
+    const context = routeState().route.context as DeferredContext;
+    const deferred = context.ssrDataDeferred;
+
+    return (deferred?.[key] ?? NEVER_PROMISE) as Promise<T>;
+  });
+
+  const value = signal<T | undefined>(undefined);
+
+  effect((onCleanup) => {
+    const promise = promiseSignal();
+    let cancelled = false;
+
+    onCleanup(() => {
+      cancelled = true;
+    });
+
+    promise.then(
+      (resolved) => {
+        if (!cancelled) {
+          value.set(resolved);
+        }
+      },
+      /* v8 ignore next 4 -- @preserve: rejection branch — `effect` swallows
+         async errors silently, so leaving the signal as `undefined` is the
+         only observable behaviour. Real error surfacing is the loader's
+         responsibility (throw → navigation rejects → app error boundary). */
+      () => {
+        // Intentional swallow — see v8 ignore note above.
+      },
+    );
+  });
+
+  return value.asReadonly();
+}

package/ssr/functions/provideHttpStatusSink.ts

@@ -0,0 +1,43 @@
+import { makeEnvironmentProviders } from "@angular/core";
+
+import { HTTP_STATUS_SINK } from "../utils/createHttpStatusSink";
+
+import type { HttpStatusSink } from "../utils/createHttpStatusSink";
+import type { EnvironmentProviders } from "@angular/core";
+
+/**
+ * Environment providers for a request-scoped `HttpStatusSink`. Pair with
+ * `createHttpStatusSink()` and read `sink.code` after the SSR render pass
+ * completes.
+ *
+ * Application bootstrap:
+ *
+ * ```ts
+ * const sink = createHttpStatusSink();
+ *
+ * await bootstrapApplication(AppRoot, {
+ *   providers: [
+ *     provideRealRouterFactory({ ... }),
+ *     provideHttpStatusSink(sink),
+ *   ],
+ * });
+ *
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ *
+ * Equivalent to:
+ *
+ * ```ts
+ * { provide: HTTP_STATUS_SINK, useValue: sink }
+ * ```
+ *
+ * Use the explicit `useValue` form when you need to compose with other
+ * application providers in a single `providers: [...]` block.
+ */
+export function provideHttpStatusSink(
+  sink: HttpStatusSink,
+): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    { provide: HTTP_STATUS_SINK, useValue: sink },
+  ]);
+}

package/ssr/ng-package.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://raw.githubusercontent.com/ng-packagr/ng-packagr/main/src/ng-package.schema.json",
+  "lib": {
+    "entryFile": "public_api.ts"
+  }
+}

package/ssr/public_api.ts

@@ -0,0 +1,35 @@
+// SSR-feature entry — Angular 21+
+//
+// Server-side and SSR-aware components/functions. Mirrors the
+// `/ssr` subpath split shipped by every other adapter (#604 + #610).
+// Trigger reached: `<ClientOnly>`, `<ServerOnly>`, `injectDeferred()`
+// — three SSR-feature exports, ≥3 threshold per
+// `.claude/SSR_FEATURE_GAPS_RU.md` §8.
+//
+// Asymmetric Angular note: Angular has no native `<Suspense>` /
+// `use(promise)` analogue, so this entry exposes the signal-based
+// `injectDeferred()` instead of `<Await>` / `<Streamed>` adapter
+// components. Consumers compose with `@if (signal()) { … } @else { … }`,
+// the `async` pipe (`from(deferredPromise)`), or native `@defer`
+// blocks for chunk-level lazy hydration.
+
+// Components
+export { ClientOnly } from "./components/ClientOnly";
+
+export { ServerOnly } from "./components/ServerOnly";
+
+export { HttpStatusCode } from "./components/HttpStatusCode";
+
+// Functions
+export { injectDeferred } from "./functions/injectDeferred";
+
+export { provideHttpStatusSink } from "./functions/provideHttpStatusSink";
+
+// Utilities
+export {
+  HTTP_STATUS_SINK,
+  createHttpStatusSink,
+} from "./utils/createHttpStatusSink";
+
+// Types
+export type { HttpStatusSink } from "./utils/createHttpStatusSink";

package/ssr/utils/createHttpStatusSink.ts

@@ -0,0 +1,61 @@
+import { InjectionToken } from "@angular/core";
+
+/**
+ * Render-scoped HTTP status sink. Created per request on the server and
+ * provided via `provideHttpStatusSink(sink)` (or directly through
+ * `{ provide: HTTP_STATUS_SINK, useValue: sink }`). Read after the SSR pass
+ * (`renderApplication` / `AngularNodeAppEngine` rendering) to apply the value
+ * to the HTTP response.
+ *
+ * Last write wins: if the rendered tree mounts more than one
+ * `<http-status-code [code]="N" />`, the value reflects the last component
+ * that ran during the render pass.
+ *
+ * No-op on the client — `<http-status-code />` injects `HTTP_STATUS_SINK`
+ * with `{ optional: true }` and skips the write when no provider is
+ * registered, so the same component tree can be hydrated without changing
+ * behaviour.
+ *
+ * Constraints:
+ * - **Per-request only.** Don't share a sink across requests; the rendered
+ *   tree mutates `code` in place. Module-level singletons leak status
+ *   between concurrent requests.
+ * - **Don't `Object.freeze` the sink.** The component writes to `.code`;
+ *   freezing makes the assignment throw under ESM strict mode.
+ * - **Pass through `REQUEST_CONTEXT`, not via `req` properties.** Wire the
+ *   sink with `angularApp.handle(req, { httpStatusSink })` and read it back
+ *   in the `HTTP_STATUS_SINK` factory via `inject(REQUEST_CONTEXT)`.
+ *   `AngularNodeAppEngine` builds a fresh Web `Request` from the
+ *   `IncomingMessage` and discards every custom property, so attaching to
+ *   `req` directly silently no-ops.
+ */
+export interface HttpStatusSink {
+  code: number | undefined;
+}
+
+export function createHttpStatusSink(): HttpStatusSink {
+  return { code: undefined };
+}
+
+/**
+ * DI token for the request-scoped HTTP status sink. Application-side wiring:
+ *
+ * ```ts
+ * import { bootstrapApplication } from "@angular/platform-browser";
+ * import { provideHttpStatusSink, createHttpStatusSink } from "@real-router/angular/ssr";
+ *
+ * const sink = createHttpStatusSink();
+ *
+ * await bootstrapApplication(AppRoot, {
+ *   providers: [
+ *     provideRealRouterFactory({ ... }),
+ *     provideHttpStatusSink(sink),
+ *   ],
+ * });
+ *
+ * response.status(sink.code ?? 200).send(html);
+ * ```
+ */
+export const HTTP_STATUS_SINK = new InjectionToken<HttpStatusSink>(
+  "HTTP_STATUS_SINK",
+);