Make runtime api stable (#77)

feat: document runtime and add adapter specific properties

docs/.vitepress/config.ts

@@ -72,6 +72,10 @@ export default defineConfig({
             text: "Using env variables",
             link: "/recipes/env-helper",
           },
+          {
+            text: "Using runtime information",
+            link: "/recipes/runtime",
+          },
         ],
       },
       {

docs/definitions.md

@@ -6,8 +6,11 @@ A function that returns a [Response](https://developer.mozilla.org/en-US/docs/We
 It will usually be associated with a _route_.
 
 ```ts twoslash
+import type { RuntimeAdapter } from "@universal-middleware/core";
+// ---cut---
 interface UniversalHandler<Context> {
-  (request: Request, context: Context): Response | Promise<Response>;
+  (request: Request, context: Context, runtime: RuntimeAdapter):
+    Response | Promise<Response>;
 }
 ```
 
@@ -24,9 +27,10 @@ Check the [recipes](/recipes/context-middleware) for details.
 
 ```ts twoslash
 type Awaitable<T> = T | Promise<T>;
-
-interface UniversalMiddleware<InContext, OutContext> { // [!code focus:9]
-  (request: Request, context: InContext):
+import type { RuntimeAdapter } from "@universal-middleware/core";
+// ---cut---
+interface UniversalMiddleware<InContext, OutContext> {
+  (request: Request, context: InContext, runtime: RuntimeAdapter):
     Awaitable<
     | Response // Can return an early Response
     | OutContext // Can return a new context. Ensures type-safe context representation

docs/recipes/context-middleware.md

@@ -3,7 +3,7 @@
 In this example, we're creating a middleware that adds a `hello` property to the [context](/definitions#context).
 This property will then be accessible to any subsequent middleware or handler.
 
-<<< @/../examples/tool/src/middlewares/context.middleware.ts
+<<< @/../examples/tool/src/middlewares/context.middleware.ts {ts twoslash}
 
 After bundling this middleware, one can then use this middleware as follows:
 

docs/recipes/env-helper.md

@@ -2,7 +2,7 @@
 
 The `env()` function helps to retrieve environment variables across all supported runtimes.
 
-```ts
+```ts twoslash
 import { env, type Get, type UniversalMiddleware } from "@universal-middleware/core";
 
 const handler = (() => (request, context, runtime) => {

docs/recipes/guard-middleware.md

@@ -2,7 +2,7 @@
 
 The following middleware is in charge of returning an early Response in case of unauthenticated user access.
 
-<<< @/../examples/tool/src/middlewares/guard.middleware.ts
+<<< @/../examples/tool/src/middlewares/guard.middleware.ts {ts twoslash}
 
 After bundling this middleware, one can then use this middleware as follows:
 

docs/recipes/headers-middleware.md

@@ -6,7 +6,7 @@ The following middleware demonstrate how to interact with or modify a Response.
 > Contrary to some middleware patterns out there, universal middlewares do not use a `next()` function. 
 > Instead, a middleware can return a function that will take the response as its first parameter.
 
-<<< @/../examples/tool/src/middlewares/headers.middleware.ts
+<<< @/../examples/tool/src/middlewares/headers.middleware.ts {ts twoslash}
 
 After bundling this middleware, one can then use this middleware as follows:
 

docs/recipes/params-handler.md

@@ -5,7 +5,7 @@ Most adapters natively support route parameters (also called _parametric path_ o
 
 We recommend to follow this next example when using route parameters:
 
-<<< @/../examples/tool/src/handlers/params.handler.ts
+<<< @/../examples/tool/src/handlers/params.handler.ts {ts twoslash}
 
 > [!NOTE]
 > For servers supporting route parameters (`app.get("/user/:name", myHandler())`), the parameters are available under `runtime.params`.

docs/recipes/runtime.md

@@ -0,0 +1,174 @@
+# Using runtime information
+
+The runtime data and original adapter parameters can be accessed through the third `runtime` parameter
+in any middleware or handler. For instance:
+
+```ts twoslash
+import { env, type Get, type UniversalMiddleware } from "@universal-middleware/core";
+
+const handler = (() => (request, context, runtime) => {
+  if (runtime.adapter === "express") {
+    runtime.req;
+    //      ^?
+  }
+}) satisfies Get<[], UniversalMiddleware>;
+```
+
+### Available properties
+
+::: code-group
+
+```ts twoslash [hono]
+// @noErrors
+import type { HonoAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<HonoAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [h3]
+// @noErrors
+import type { H3Adapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<H3Adapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [hattip]
+// @noErrors
+import type { HattipAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<HattipAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [cloudflare-worker]
+// @noErrors
+import type { CloudflareWorkerAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<CloudflareWorkerAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [cloudflare-pages]
+// @noErrors
+import type { CloudflarePagesAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<CloudflarePagesAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [express]
+// @noErrors
+import type { ExpressAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<ExpressAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [fastify]
+// @noErrors
+import type { FastifyAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<FastifyAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [elysia]
+// @noErrors
+import type { ElysiaAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<ElysiaAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [vercel-edge]
+// @noErrors
+import type { VercelEdgeAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<VercelEdgeAdapter>;
+//   ^^^^^^^
+```
+
+```ts twoslash [vercel-node]
+// @noErrors
+import type { VercelNodeAdapter } from "@universal-middleware/core";
+
+export type Explain<A extends any> =
+  A extends Function
+    ? A
+    : {[K in keyof A]: A[K]} & unknown
+
+// ---cut---
+// hover me
+type Runtime = Explain<VercelNodeAdapter>;
+//   ^^^^^^^
+```
+
+:::
+
+> [!NOTE]
+> All runtime types are defined in [types.ts](https://github.com/magne4000/universal-middleware/blob/main/packages/core/src/types.ts)

examples/tool/src/middlewares/context.middleware.ts

@@ -3,7 +3,7 @@
 
 import type { Get, UniversalMiddleware } from "@universal-middleware/core";
 
-const contextMiddleware = ((value) => (request, ctx) => {
+const contextMiddleware = ((value) => (request, ctx, runtime) => {
   // Return the new universal context, thus keeping complete type safety
   // A less typesafe way to do the same thing would be to `ctx.something = value` and return nothing
   return {

examples/tool/src/middlewares/guard.middleware.ts

@@ -9,7 +9,7 @@ interface User {
 }
 
 // This middleware will return an early Response for unauthenticated users
-const guardMiddleware = (() => (request, ctx) => {
+const guardMiddleware = (() => (request, ctx, runtime) => {
   if (!ctx?.user) {
     return new Response("Unauthorized", {
       status: 401,

examples/tool/src/middlewares/headers.middleware.ts

@@ -4,7 +4,7 @@
 import type { Get, UniversalMiddleware } from "@universal-middleware/core";
 
 // This middleware will add a `X-Universal-Hello` header to all responses
-const headersMiddleware = (() => (request, ctx) => {
+const headersMiddleware = (() => (request, ctx, runtime) => {
   return (response) => {
     // `ctx.hello` exists if it has been set by another middleware
     response.headers.set("X-Universal-Hello", ctx.hello ?? "world");

packages/adapter-cloudflare/package.json

@@ -25,7 +25,7 @@
     "@universal-middleware/core": "workspace:^"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20241127.0",
+    "@cloudflare/workers-types": "catalog:",
     "@swc/core": "catalog:",
     "@types/node": "catalog:",
     "@universal-middleware/tests": "workspace:*",

packages/adapter-cloudflare/src/common.ts

@@ -136,10 +136,13 @@ export function getRuntime(
 ): RuntimeAdapter {
   const isContext = args.length === 1;
 
+  const key = isContext ? "cloudflare-pages" : "cloudflare-worker";
+
   return getAdapterRuntime(
     isContext ? "cloudflare-pages" : "cloudflare-worker",
     {
       params: isContext ? ((args[0].params as Record<string, string>) ?? undefined) : undefined,
+      [key]: isContext ? args[0] : { env: args[0], ctx: args[1] },
     },
     {
       env: isContext ? args[0].env : args[0],

packages/adapter-elysia/package.json

@@ -25,7 +25,7 @@
     "@universal-middleware/core": "workspace:^"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20241127.0",
+    "@cloudflare/workers-types": "catalog:",
     "@swc/core": "catalog:",
     "@types/node": "catalog:",
     "@universal-middleware/tests": "workspace:*",

packages/adapter-elysia/src/common.ts

@@ -145,6 +145,7 @@ export function getRuntime(elysiaContext: ElysiaContext): RuntimeAdapter {
     "elysia",
     {
       params,
+      elysia: elysiaContext,
     },
     cloudflareContext,
   );

packages/adapter-express/src/common.ts

@@ -175,5 +175,9 @@ export function getRuntime(request: DecoratedRequest, response: DecoratedServerR
     params: request.params,
     req: request as IncomingMessage,
     res: response,
+    express: Object.freeze({
+      req: request as IncomingMessage,
+      res: response,
+    }),
   });
 }

packages/adapter-fastify/src/common.ts

@@ -255,5 +255,9 @@ export function getRuntime(request: FastifyRequest, reply: FastifyReply): Runtim
     params: request.params as Record<string, string> | undefined,
     req: request.raw as IncomingMessage,
     res: reply.raw,
+    fastify: Object.freeze({
+      request: request,
+      reply: reply,
+    }),
   });
 }

packages/adapter-h3/src/common.ts

@@ -162,6 +162,7 @@ export function getRuntime(event: H3Event): RuntimeAdapter {
     "h3",
     {
       params: event.context.params,
+      h3: event,
     },
     {
       req: event.node.req,

packages/adapter-hattip/package.json

@@ -32,7 +32,7 @@
     "@hattip/adapter-deno": "^0.0.49",
     "@hattip/adapter-node": "^0.0.49",
     "@hattip/compose": "^0.0.49",
-    "@hattip/core": "^0.0.49",
+    "@hattip/core": "catalog:",
     "@hattip/cors": "^0.0.49",
     "@hattip/router": "catalog:",
     "@swc/core": "catalog:",

packages/adapter-hattip/src/common.ts

@@ -91,6 +91,7 @@ export function getRuntime(context: AdapterRequestContext): RuntimeAdapter {
     "hattip",
     {
       params: "params" in context ? (context.params as Record<string, string>) : undefined,
+      hattip: context,
     },
     {
       // biome-ignore lint/suspicious/noExplicitAny: <explanation>

packages/adapter-hono/src/common.ts

@@ -135,6 +135,7 @@ export function getRuntime(honoContext: HonoContext): RuntimeAdapter {
     "hono",
     {
       params,
+      hono: honoContext,
     },
     {
       env: honoContext.env,