Resolves #1487 (prototype of the refined proposal). Related: #1478 / #1484.

What

You start a timer, subscribe to something, or open an upstream connection inside a request handler. Where do you clean it up? Today the answer depends on where your app runs: on Node.js you can listen to res.on("close"), on Bun / Deno / Cloudflare Workers there is no reliable place at all — so timers keep ticking after clients are long gone.

onDispose(event, cb) is one answer that works on every runtime:

import { onDispose } from "h3";

app.get("/sse", (event) => {
  const interval = setInterval(() => sse.push("tick"), 1000);

  onDispose(event, () => clearInterval(interval));

  // ... return a streaming response
});

The callback runs exactly once, when the request is truly over — the response finished streaming, the client disconnected, or something errored mid-stream. On disconnect/error, it receives the reason.

Like other h3 utils (getQuery(event), readBody(event)), it's just an importable function — apps that never use it don't ship a single byte of it.

How

• Node (event.runtime.node.res present): observes res "close" — accurate for streaming and non-streaming bodies, and the body is never wrapped, so srvx's FastResponse _toNodeResponse fast paths stay intact. Premature close disposes with an AbortError DOMException (or res.errored).
• Web runtimes: a streaming body is piped through an identity TransformStream; the pipeTo promise settles on all three termination paths (normal end → resolve, consumer cancel → reject with the cancel reason, which also propagates upstream, source error → reject). Bodyless responses dispose at response production — once the Response is handed to the runtime, delivery is not observable on web (per the fidelity table in Add event.onDispose(): a portable end-of-event hook for resource cleanup #1487).
• Opt-in, lazily armed, and tree-shakable: the first onDispose registration installs an observe function on the event; toResponse only keeps a symbol check + observe call at its single final exit (after onResponse resolves, so the hook ordering holds on every path). Because registration carries the machinery, apps that never import onDispose don't bundle any of it — this is why it is a util rather than an H3Event method (a method would anchor ~1 kB min in every core bundle).
• Hardened once, in core: callbacks run in registration order; sync throws and async rejections are both absorbed (reported via console.error unless silent) — the exact rake found in fix(event-stream): correct stream teardown on close and client disconnect #1484. Pending async callbacks are handed to event.waitUntil() for serverless runtimes. Registering after disposal fires immediately with the recorded reason.

Consumer: createEventStream

The Node-only res.once("close", () => this.close()) autoclose is replaced with onDispose(event, () => this.close()). This fixes two pre-existing web-runtime leaks (verified failing on main, matrix web target):

• a stream that is created but never send()-ed never ran its onClosed callbacks (not covered by fix(event-stream): correct stream teardown on close and client disconnect #1484);
• a client disconnect never triggered autoclose, so pushes kept running per connection.

Note: onClosed's own disconnect-path bug (writer.closed rejection swallowed) remains #1484's scope — this PR intentionally doesn't touch it.

Costs

• Bundle: +~105 B min / +~42 B gzip on the tracked core bundles (the symbol + arm check in toResponse); the ~1 kB machinery is bundled only where onDispose (or createEventStream) is imported. Limits ratcheted with the same tight headroom as before (main sat 32 B under).
• Runtime: one symbol check per request when unused; the per-chunk queue hop exists only for events that registered a callback and have a streaming body on a non-Node runtime.

Tests

test/dispose.test.ts (matrix, 8 cases): non-streaming fire, mid-stream non-fire + fire on full consumption, disconnect reason propagation (web: exact cancel reason; node: abort error), onResponse ordering, callback order + sync/async error absorption, late registration, unmodified fast path, status/header preservation on wrapped responses. Plus the two SSE regression tests above. Full suite green (1543 passed), lint/typecheck/build clean.

Caveats / open questions

• Registration is only guaranteed to observe the end of the event when made during request handling — on web runtimes a first registration made mid-stream can never attach the observer (documented; Node is immune).
• EventStream autoclose now depends on the event flowing through toResponse (true for any H3 app). A consumer invoking handlers directly without toResponse loses the old Node-only fallback.
• Body-wrapping perf on the streaming path is unbenchmarked beyond "opt-in only"; happy to add a mitata case if wanted.
• event.disposed: Promise<unknown> remains a possible alternative/additional shape (see Add event.onDispose(): a portable end-of-event hook for resource cleanup #1487) — trivial to derive from this registry if preferred (though as an H3Event member it would re-anchor the machinery in core bundles).
• Naming: onDispose(event, cb) sits next to the onRequest/onResponse/onError middleware factories in the public namespace despite having a different shape (per-event util). Open to a different name if that reads as a footgun.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added onDispose to register one-time per-event cleanup callbacks that run when the event/response lifecycle fully ends, including cancellation and errors.
  • Disposal is now integrated with the response flow to ensure the returned response participates in end-of-event cleanup.
• Documentation
  • Added onDispose docs covering argument semantics, callback timing relative to onResponse, late registration, and failure handling.
• Bug Fixes
  • Improved end-of-stream handling for event streams and SSE, including streams that are never sent and automatic cleanup on client disconnect.
• Tests
  • Added disposal and SSE lifecycle test coverage, updated export snapshots, and tightened bundle-size benchmark thresholds.