@nifrajs/core 1.3.1 → 1.5.0

package/src/server/server.ts

@@ -11,6 +11,7 @@ import type { Context, Platform, ResponseControls, RouteSchema } from "./context
 import { type CookieOptions, parseCookies, serializeCookie } from "./cookies.ts"
 import { jsonLogger, type Logger } from "./logger.ts"
 import type { AddRoute, EmptyRegistry, OutputOf, Registry, RouteInfoFor } from "./registry.ts"
+import { type SSEInit, sse, type TypedSSEStream, typedSSEStream } from "./sse.ts"
 import type {
   StandardWebSocket,
   TopicRegistry,
@@ -133,6 +134,7 @@ type RawAround = <T>(ctx: RawContext, next: () => MaybePromise<T>) => MaybePromi
 export type OnRequestResult = Response | Request | undefined
 type RawOnRequest = (req: Request) => MaybePromise<OnRequestResult>
 type RawOnResponse = (response: Response, req: Request) => MaybePromise<Response>
+type RawOnResponseFinalized = (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
 
 interface RouteEntry {
   readonly handler: InternalHandler
@@ -350,9 +352,18 @@ export interface Middleware {
   readonly beforeHandle?: (context: Context) => MaybePromise<unknown>
   readonly afterHandle?: (result: unknown, context: Context) => MaybePromise<unknown>
   readonly onResponse?: (response: Response, req: Request) => MaybePromise<Response>
+  readonly onResponseFinalized?: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>
   readonly onError?: (error: unknown, context: Context) => MaybePromise<unknown>
 }
 
+/** The terminal response-pipeline outcome observed after every transforming `onResponse` hook. */
+export interface ResponseFinalization {
+  /** The final response, or the last response available when a transformation failed. */
+  readonly response: Response
+  /** A response-hook failure. Terminal observers run fail-open before the error is rethrown. */
+  readonly error?: unknown
+}
+
 // A plugin operates over arbitrary Server shapes; `any` here is the standard framework escape hatch
 // (the precise threading happens at the `use` call site, which is generic over the *concrete* `this`).
 // biome-ignore lint/suspicious/noExplicitAny: plugins are generic over any Server's Registry/Context
@@ -1111,6 +1122,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
   private readonly aroundHooks: RawAround[]
   private readonly onRequestHooks: RawOnRequest[]
   private readonly onResponseHooks: RawOnResponse[]
+  private readonly onResponseFinalizedHooks: RawOnResponseFinalized[]
   private readonly responseRequests: WeakMap<Request, Request>
   /** Names of plugins/middleware already applied via `use` — for idempotent dedupe. */
   private readonly appliedPlugins: Set<string>
@@ -1139,6 +1151,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     this.aroundHooks = []
     this.onRequestHooks = []
     this.onResponseHooks = []
+    this.onResponseFinalizedHooks = []
     this.responseRequests = new WeakMap()
     this.appliedPlugins = new Set()
     this.mcpResourceList = []
@@ -1200,6 +1213,14 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this
   }
 
+  /** Observe the terminal response after all transformations. Observers are ordered and fail-open. */
+  onResponseFinalized(
+    fn: (outcome: ResponseFinalization, req: Request) => MaybePromise<void>,
+  ): this {
+    this.onResponseFinalizedHooks.push(fn)
+    return this
+  }
+
   /**
    * Apply a type-**identity** plugin ({@link IdentityPlugin}, from {@link defineIdentityPlugin}) — it
    * registers routes/hooks but doesn't change the types, so this returns `this` with the route registry
@@ -1240,6 +1261,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     if (arg.beforeHandle !== undefined) this.beforeHandle(arg.beforeHandle)
     if (arg.afterHandle !== undefined) this.afterHandle(arg.afterHandle)
     if (arg.onResponse !== undefined) this.onResponse(arg.onResponse)
+    if (arg.onResponseFinalized !== undefined) this.onResponseFinalized(arg.onResponseFinalized)
     if (arg.onError !== undefined) this.onError(arg.onError)
     return this
   }
@@ -1261,6 +1283,43 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return this.route("GET", path, schemaOrHandler, handler)
   }
 
+  /**
+   * Register a **typed SSE route** — a GET endpoint streaming `text/event-stream` whose event
+   * payloads are contracted by `schema.sse`. The handler receives the validated context plus a
+   * {@link TypedSSEStream}: `stream.send(event)` is compile-time-checked against the schema and
+   * JSON-serialized into the SSE `data:` field. The typed client sees the marker and grows a
+   * `.subscribe(onEvent)` for the route with the same payload type — end-to-end typed streaming.
+   *
+   *   const app = server().sse("/feed", { sse: t.object({ id: t.integer(), title: t.string() }) },
+   *     async (c, stream) => {
+   *       stream.send({ id: 1, title: "hello" })          // typed
+   *       await waitForDisconnect(stream.signal)
+   *     },
+   *     { keepAlive: 15_000 })
+   *
+   *   // client: const off = api.feed.subscribe((post) => console.log(post.title))
+   *
+   * `init` passes through to the underlying {@link sse} helper (`keepAlive`, extra headers). The
+   * connection closes when the handler resolves, `stream.close()` runs, or the client disconnects
+   * (`stream.signal`). Query/body schemas validate exactly as on any other route.
+   */
+  sse<Path extends string, S extends RouteSchema & { sse: StandardSchemaV1 }>(
+    path: Path,
+    schema: S,
+    run: (
+      context: Context<Path, S> & Ctx,
+      stream: TypedSSEStream<InferOutput<S["sse"]>>,
+    ) => void | Promise<void>,
+    init?: SSEInit,
+  ): Server<AddRoute<R, "GET", Path, RouteInfoFor<Path, S, Response>>, Ctx> {
+    const handler = (context: Context<Path, S> & Ctx): Response =>
+      sse(context, (stream) => run(context, typedSSEStream(stream)), init)
+    return this.route("GET", path, schema, handler as unknown as ErasedHandler) as Server<
+      AddRoute<R, "GET", Path, RouteInfoFor<Path, S, Response>>,
+      Ctx
+    >
+  }
+
   post<Path extends string, S extends RouteSchema, H extends Handler<Path, S, Ctx>>(
     path: Path,
     schema: S,
@@ -1597,14 +1656,16 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
       RESPONSE_TIMEOUT,
       true,
     )
-    if (this.onResponseHooks.length === 0) {
+    if (this.onResponseHooks.length === 0 && this.onResponseFinalizedHooks.length === 0) {
       return outcome
     }
     // onResponse sees every response — success, validation error, 404/405, timeout, onRequest
     // short-circuit; normalize to a promise, then thread through the hooks.
     return outcome instanceof Promise
-      ? outcome.then((response) => this.applyOnResponse(response, this.takeResponseRequest(source)))
-      : this.applyOnResponse(outcome, this.takeResponseRequest(source))
+      ? outcome.then((response) =>
+          this.applyOnResponseAndFinalize(response, this.takeResponseRequest(source)),
+        )
+      : this.applyOnResponseAndFinalize(outcome, this.takeResponseRequest(source))
   }
 
   /**
@@ -1625,7 +1686,7 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     platform?: Platform<EnvOf<Ctx>>,
   ): MaybePromise<NodeServeOutcome> {
     // onResponse hooks transform a Response, so they force the Web path; wrap its result.
-    if (this.onResponseHooks.length > 0) {
+    if (this.onResponseHooks.length > 0 || this.onResponseFinalizedHooks.length > 0) {
       const response = this.fetchSource(source, platform)
       return response instanceof Promise
         ? response.then((settled) => ({ kind: "response", response: settled }))
@@ -2428,6 +2489,66 @@ export class Server<R extends Registry = EmptyRegistry, Ctx = EmptyContext> {
     return current
   }
 
+  private applyOnResponseAndFinalize(response: Response, req: Request): MaybePromise<Response> {
+    try {
+      const transformed = this.applyOnResponse(response, req)
+      return transformed instanceof Promise
+        ? transformed.then(
+            (settled) => this.completeResponseFinalization({ response: settled }, req),
+            (error) => this.failResponseFinalization(response, error, req),
+          )
+        : this.completeResponseFinalization({ response: transformed }, req)
+    } catch (error) {
+      return this.failResponseFinalization(response, error, req)
+    }
+  }
+
+  private completeResponseFinalization(
+    outcome: ResponseFinalization,
+    req: Request,
+  ): MaybePromise<Response> {
+    const notified = this.notifyResponseFinalized(outcome, req)
+    return notified instanceof Promise ? notified.then(() => outcome.response) : outcome.response
+  }
+
+  private failResponseFinalization(
+    response: Response,
+    error: unknown,
+    req: Request,
+  ): Promise<never> | never {
+    const notified = this.notifyResponseFinalized({ response, error }, req)
+    if (notified instanceof Promise) {
+      return notified.then(() => {
+        throw error
+      })
+    }
+    throw error
+  }
+
+  /** Notify terminal observers in order while isolating both sync and async failures. */
+  private notifyResponseFinalized(outcome: ResponseFinalization, req: Request): MaybePromise<void> {
+    let pending: Promise<void> | undefined
+    for (const hook of this.onResponseFinalizedHooks) {
+      if (pending !== undefined) {
+        pending = pending.then(async () => {
+          try {
+            await hook(outcome, req)
+          } catch {
+            // Terminal observation must never change request behavior.
+          }
+        })
+        continue
+      }
+      try {
+        const result = hook(outcome, req)
+        if (result instanceof Promise) pending = result.catch(() => {})
+      } catch {
+        // Terminal observation must never change request behavior.
+      }
+    }
+    return pending
+  }
+
   /** Async tail of {@link applyOnResponse}: runs the remaining hooks once one has gone async. */
   private async continueOnResponse(
     response: Response,

package/src/server/sse.ts

@@ -57,6 +57,35 @@ export interface SSEInit {
   readonly keepAlive?: number
 }
 
+/**
+ * The stream handed to an `app.sse()` handler: `send` takes the route's TYPED event payload and
+ * serializes it (JSON) into the SSE `data:` field — the compile-time half of the `sse` contract.
+ */
+export interface TypedSSEStream<Event> {
+  /** Send one typed event. `init` sets the optional SSE frame fields (`event`, `id`, `retry`). */
+  send(event: Event, init?: Pick<SSEMessage, "event" | "id" | "retry">): void
+  /** Send a `: comment` line (e.g. an explicit ping). */
+  comment(text: string): void
+  /** End the stream now. */
+  close(): void
+  /** Aborts when the client disconnects — use it to tear down subscriptions/loops. */
+  readonly signal: AbortSignal
+}
+
+/** Wrap a raw {@link SSEStream} in the typed, JSON-serializing surface `app.sse()` hands out. */
+export function typedSSEStream<Event>(stream: SSEStream): TypedSSEStream<Event> {
+  return {
+    send(event, init = {}) {
+      stream.send({ ...init, data: JSON.stringify(event) })
+    },
+    comment(text) {
+      stream.send({ comment: text })
+    },
+    close: stream.close,
+    signal: stream.signal,
+  }
+}
+
 const CRLF = /[\r\n]/g
 const LINE_SPLIT = /\r\n|\r|\n/