feat(context): introduce c.var

[yusukebe]

This PR introduces two new features: the ability to set variables using Middleware generics and accessing them via c.var.

Currently, you can globally define variable types using generics for Hono.

type Client = 'foo client'

const app = new Hono<{
  Variables: {
    client: Client
  }
}>()

Alternatively, you can specify them for a specific middleware using ContextVariableMap:

// JWT middleare
declare module '../../context' { // Or you can write `declare module 'hono'`
  interface ContextVariableMap {
    jwtPayload: any
  }
}

The challenge here is that using ContextVariableMap makes it globally available. For instance, after importing the JWT middleware, you can access jwtPayload in any handler.

With this PR, you can confine middleware-defined variables to specific handlers where the middleware is applied.

const oneApiMiddleware: MiddlewareHandler<{
  Variables: {
    client: Client
  }
}> = async (c, next) => {
  c.set('client', new Client())
  await next()
}

app.get('/foo', oneApiMiddleware, (c) => {
  const client = c.get('client') // `client` is accessible only in this handler
  // ...
  return c.json({})
})

This offers a scoped approach to variable type availability.

The second feature is c.var. While the conventional method to access the actual value of a variable is c.get():

const client = c.get('client')

With c.var, you can use a more intuitive syntax:

const result = c.var.client.oneMethod()

The combination of these two features will provide a powerful tool for developers:

const app = new Hono()

const echoMiddleware: MiddlewareHandler<{
  Variables: {
    echo: (str: string) => string
  }
}> = async (c, next) => {
  c.set('echo', (str) => str)
  await next()
}

app.get('/echo', echoMiddleware, (c) => {
  return c.text(c.var.echo('Hello!'))
})

This was discussed in issue #414 and is now being realized.

[yusukebe]

Hi @usualoma , @ThatOneBro , and others.

What do you think about this feature? I think this is good because it will achieve big things with minimal change of the APIs.

[ThatOneBro]

I think this makes a lot of sense overall. 👍 LGTM

[yusukebe]

With this commit, I've set the properties to read-only. This is to prevent confusion, emphasizing that users should exclusively use c.set() to assign values.

[Eduard-Hasa]

const app = new Hono()

const echoMiddleware: MiddlewareHandler<{
  Variables: {
    echo: (str: string) => string
  }
}> = async (c, next) => {
  c.set('echo', (str) => str)
  await next()
}

app.get('/echo', echoMiddleware, (c) => {
  return c.text(c.var.echo('Hello!'))
})

I think there is a large gap in documentation/public knowledge on how to use honojs with cloudflare durable objects in the sense that there is no way shown how to access durable object storage in the route handlers. Would the c.set() and c.text(c.var.echo('Hello!')) solution be good to store and access durable object storage in routes?