Augment `H3Context` to improve `event.context` typing

[stafyniaksacha]

Describe the feature

With 1.8.0 can now have better typing for query parameters and body content using eventHandler generic.
We also have a proper way to define per event middlewares stack using onRequest

The issue is that it's difficult to type event context.

We can use typescript interface augmentation, but this impact all events in the project:

declare module 'h3' {
  interface H3EventContext {
    auth: { name: string }
  }
}

export default defineEventHandler(async (event) => {
  event.context.auth.name // string
}

Before 1.8.0, we could create a custom eventHandler wrapper and use an extended version of H3Event:

import type { H3Event, H3EventContext } from 'h3'

// custom event
interface H3CustomEvent extends H3Event {
  context: H3EventContext & {
    auth: { name: string }
  }
}

// custom event handler
function defineCustomEventHandler<T>(handler: (event: H3CustomEvent) => T) {
  return defineEventHandler(async (event) => {
    event.context.auth = { name: 'username' }
    eturn handler(event as H3CustomEvent)
  }
})

// usage
export default defineCustomEventHandler(async (event) => {
  event.context.auth.name // string
}

Same wrapper with `1.8.0`

// EventHandlerRequest, EventHandlerResponse, EventHandler are not exported
interface EventHandlerRequest {
  body?: any
  query?: QueryObject
}
type EventHandlerResponse<T = any> = T | Promise<T>

interface EventHandler<
  Request extends EventHandlerRequest = EventHandlerRequest,
  Response extends EventHandlerResponse = EventHandlerResponse,
> {
  __is_handler__?: true
  (event: H3Event<Request>): Response
}

// custom event
interface H3CustomEvent<T extends EventHandlerRequest = EventHandlerRequest>
  extends H3Event<T> {
  context: H3EventContext & {
    auth: { name: string }
  }
}

// custom event handler
export function customEventHandler<
  Request extends EventHandlerRequest = EventHandlerRequest,
  Response extends EventHandlerResponse = EventHandlerResponse,
>(
  handler: EventHandler<
    Request extends EventHandlerRequest ? Request : EventHandlerRequest,
    Request extends EventHandlerRequest ? Response : Request
  >,
): EventHandler<
  Request extends EventHandlerRequest ? Request : EventHandlerRequest,
  Request extends EventHandlerRequest ? Response : Request
> {
  //
  return eventHandler((event) => {
    event.context.auth = { name: 'username' }

    return handler(event as H3CustomEvent<Request>)
  })
}

// usage
export default customEventHandler((event) => {
  event.context.auth.name // string
})

Since usage of generics (and methods overloading), it's harder to wrap.

How about extending context with EventHandlerRequest, same as query and body like:

const auth = defineRequestMiddleware<{
  context: {
    auth: {
      name: string
    }
  }
}>((event) => {
  event.context.auth.name // string
})

export default eventHandler<{
  context: {
    auth: {
      name: string
    }
  }
}>({
  onRequest: [auth],
  async handler(event) {
    event.context.auth.name // string
  },
})

Additional information

• Would you be willing to help implement this feature?

[pi0]

Having context in request types is a good idea!

We had been thinking with @danielroe to consider doing this. (as part of #496 to also allow typing validated read body into event.context.body)

[productdevbook]

@pi0 In v2, H3EventContext is an exported interface (not a type alias), so standard TypeScript declaration merging works:

declare module "h3" {
  interface H3EventContext {
    user?: { id: string; name: string };
  }
}

The interface already has typed properties: params, matchedRoute, sessions, clientAddress, basicAuth.

Can this be closed as resolved?

[gulshan]

Is it possible to include context in the generic parameters of middlewares and event handlers? While type merging applies globally across the entire application, allowing the context type to be set on a case-by-case basis could improve type safety.
@pi0 @productdevbook

[gulshan]

The basic idea of propagating the context type is this-

class MyEvent<_ContextT extends Record<string, unknown> = Record<string, any>> {
  public context: _ContextT;

  constructor(context?: _ContextT) {
    this.context = (context ?? {}) as _ContextT;
  }

  addContext<K extends string, V>(
    key: K,
    val: V
  ): MyEvent<Record<K, V> & _ContextT> {
    (this.context as any)[key] = val;
    return this as MyEvent<Record<K, V> & _ContextT>;
  }
}

let myEvent = new MyEvent()
  .addContext('user', { name: 'Alice' })
  .addContext('isAdmin', true);

let user = myEvent.context.user; // Type is { name: string }
let isAdmin =myEvent.context.isAdmin; // Type is boolean
let anything = myEvent.context.anything; // Type is any

But could not figure out how it should be applied in H3. Also, the method to extend the context will most probably be in the H3App. But the context is in the H3Event.

[gulshan]

Created a PR #1379 which supports inferred context types, like this code-

import { H3 } from "h3";

let app = new H3()
  .addEventContext("auth", (event) => event.req.headers.get("authorization"))
  .addEventContext("user", { name: "John Doe", email: "john.doe@example.com" });

app.get("/", (event) => {
  console.log(event.context.auth); // context contains key 'auth' of type 'string | null'
  console.log(event.context.user); // context contains key 'user' of type { name: string, email: string }
  return 'Hello World';
});

app.use((event) => {
  console.log(event.context.user); // context contains key 'user' of type { name: string, email: string }
});

Requesting to check, using npm i https://pkg.pr.new/h3@1379.
Also, can there a better name for the method addEventContext?