[RFC] Server-timing utility

Describe the feature

Hey all 👋🏻

right now, Nitro has very low-level support for adding Server-Timing headers. While it is possible to use, it feels like DX could be improved a lot here. Thus, I'd like to suggest this RFC!

Current state

As mentioned, the support for adding server timing already exists and is realized via globalThis. This works, but has some shortcomings:

export default defineEventHandler(async () => {
  globalThis.__timing__.logStart('MY-LABEL')
  someFunction() // Do something here
  globalThis.__timing__.logEnd('MY-LABEL')
})

1. TypeScript support only work by defining types on your own via addition .d.ts file:

// env.d.ts

declare global {
  var __timing__: {
    logStart: (id: string) => void
    logEnd: (id: string) => void
  }
}

export { }

2. No documentation. While the timing option is documented, there is no example or guide on how to actually use it.

3. When timing is disabled, the above code will fail because no __timing__ object will be injected via timing middleware.

4. Lengthy code. Because the current API is rather low-level, the code is repetitive.

5. With the above code, server timings are not cleared and will persist through requests every now and then, mainly in dev.

Idea

Instead of using the low-level API directly, I propose to add a utility which will use the API under the hood but has improved DX, full TS support and will do nothing when timing is disabled. Ideally, it will even be treeshaken in this case (and replaced with a no-op function)

API

For the API, I was thinking about the following:

• withServerTiming(fn, label) - A "wrapper" function, that will start server timing tracking before the function and will stop it after it was executed.

• startServerTiming(label) - Starts server timing with certain label

• stopServerTiming(label) - Stops server timing with certain label

Summary

This RFC proposes a Nitro utility to improve DX when adding Server-Timing headers. It will do nothing, when timing is disabled and will add info otherwise.

Additional information

• Would you be willing to help implement this feature?

Start with src/runtime/timing.ts and the documented timing option to understand the existing globalThis API and middleware behavior. Compare the RFC's withServerTiming, startServerTiming, and stopServerTiming proposal against the disabled-timing and request-cleanup cases. Done means the utility has typed usage, safely does nothing when timing is disabled, and includes an example or guide.