@znight/http 0.1.2 → 0.1.4

package/src/adapters/node-io.ts

@@ -56,47 +56,84 @@ export function readNodeBody(request: IncomingMessage, limit: number): Promise<U
     request.resume()
     return Promise.reject(payloadTooLarge(limit))
   }
+  // a read in progress (the adapters read a body once: not expected)
+  const reading = (request as ReadingRequest)[BODY_READ]
+  if (reading != null) return reading.promise
   if (consumedElsewhere(request)) return Promise.reject(consumedError())
   if (request.readableEnded) return Promise.resolve(new Uint8Array(0))
   if (request.destroyed) return Promise.reject(new BadRequestException('The request was aborted'))
-  return new Promise((resolve, reject) => {
-    const chunks: Uint8Array[] = []
-    let size = 0
-    const cleanup = (): void => {
-      request.off('data', onData)
-      request.off('end', onEnd)
-      request.off('error', onError)
-      request.off('close', onClose)
-    }
-    const onData = (chunk: Uint8Array | string): void => {
-      const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk
-      size += bytes.byteLength
-      if (size > limit) {
-        cleanup()
-        request.resume() // discard the rest; the 413 response closes the connection
-        reject(payloadTooLarge(limit))
-        return
-      }
-      chunks.push(bytes)
-    }
-    const onEnd = (): void => {
-      cleanup()
-      resolve(concat(chunks, size))
-    }
-    const onError = (error: Error): void => {
-      cleanup()
-      reject(new BadRequestException('Failed to read the request body', undefined, { cause: error }))
-    }
-    const onClose = (): void => {
-      if (request.complete) return
-      cleanup()
-      reject(new BadRequestException('The request was aborted'))
-    }
-    request.on('data', onData)
-    request.on('end', onEnd)
-    request.on('error', onError)
-    request.on('close', onClose)
+  let resolve!: (bytes: Uint8Array) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<Uint8Array>((onRead, onError) => {
+    resolve = onRead
+    reject = onError
   })
+  ;(request as ReadingRequest)[BODY_READ] = { limit, chunks: [], size: 0, resolve, reject, promise }
+  if (reading === undefined) {
+    request.on('data', onBodyData)
+    request.on('end', onBodyEnd)
+    request.on('error', onBodyError)
+    request.on('close', onBodyClose)
+  }
+  return promise
+}
+
+/**
+ * The state of the body read by {@link readNodeBody}, on its request: `null` once it is over (the
+ * listeners stay), `undefined` before.
+ */
+const BODY_READ = Symbol('znight.bodyRead')
+
+interface BodyRead {
+  readonly limit: number
+  readonly chunks: Uint8Array[]
+  size: number
+  readonly resolve: (bytes: Uint8Array) => void
+  readonly reject: (error: unknown) => void
+  readonly promise: Promise<Uint8Array>
+}
+
+type ReadingRequest = IncomingMessage & { [BODY_READ]?: BodyRead | null }
+
+// The listeners of readNodeBody: shared functions (`this` is the request), no closure per request.
+// They stay attached once the read is over (removing them costs a lot more than leaving them): they
+// then do nothing. Node.js emits `error` on a destroyed request only when it has listeners, so the
+// `error` listener left behind changes nothing either.
+
+/** Stops reading: returns the state of the read (`undefined` when it is already over). */
+function stopBodyRead(request: ReadingRequest): BodyRead | undefined {
+  const read = request[BODY_READ]
+  if (read == null) return undefined
+  request[BODY_READ] = null
+  return read
+}
+
+function onBodyData(this: ReadingRequest, chunk: Uint8Array | string): void {
+  const read = this[BODY_READ]
+  if (read == null) return
+  const bytes = typeof chunk === 'string' ? Buffer.from(chunk) : chunk
+  read.size += bytes.byteLength
+  if (read.size > read.limit) {
+    stopBodyRead(this)
+    this.resume() // discard the rest; the 413 response closes the connection
+    read.reject(payloadTooLarge(read.limit))
+    return
+  }
+  read.chunks.push(bytes)
+}
+
+function onBodyEnd(this: ReadingRequest): void {
+  const read = stopBodyRead(this)
+  read?.resolve(concat(read.chunks, read.size))
+}
+
+function onBodyError(this: ReadingRequest, error: Error): void {
+  stopBodyRead(this)?.reject(new BadRequestException('Failed to read the request body', undefined, { cause: error }))
+}
+
+function onBodyClose(this: ReadingRequest): void {
+  if (this.complete) return
+  stopBodyRead(this)?.reject(new BadRequestException('The request was aborted'))
 }
 
 /**
@@ -181,11 +218,13 @@ export interface NodeRequestOptions {
 export function nodeAdapterRequest(
   request: IncomingMessage,
   response: ServerResponse,
-  options: NodeRequestOptions = {},
+  options: NodeRequestOptions = NO_OPTIONS,
 ): AdapterRequest {
   return new NodeAdapterRequest(request, response, options)
 }
 
+const NO_OPTIONS: NodeRequestOptions = Object.freeze({})
+
 /** A Node.js request/response pair as an {@link AdapterRequest} (a class: no closure per request). */
 class NodeAdapterRequest implements AdapterRequest {
   readonly method: string
@@ -269,7 +308,10 @@ export function writeNodeReply(response: ServerResponse, reply: AdapterReply): v
   try {
     // one call (merged over headers set earlier with setHeader(), e.g. by Express middleware); the
     // cookies set earlier are kept before the reply's own (writeHead would replace them)
-    const headers = withNativeCookies(response.getHeader('set-cookie'), reply.headers)
+    const headers =
+      reply.headers['set-cookie'] === undefined
+        ? reply.headers
+        : withNativeCookies(response.getHeader('set-cookie'), reply.headers)
     response.writeHead(reply.status, headers as OutgoingHttpHeaders)
   } catch {
     // invalid header name or value set by user code
@@ -334,44 +376,72 @@ export function writeNodeFailure(response: ServerResponse): void {
   response.end('{"statusCode":500,"error":"Internal Server Error"}')
 }
 
+/** The tracker of a socket (see {@link ConnectionTracker}). */
+const TRACKER = Symbol('znight.tracker')
+/** The number of requests in progress on a tracked socket. */
+const ACTIVE = Symbol('znight.active')
+
+interface TrackedSocket extends Socket {
+  [TRACKER]?: ConnectionTracker
+  [ACTIVE]?: number
+}
+
 /**
  * Tracks the connections of a `node:http` server to close them on shutdown: idle keep-alive
  * connections first (graceful), every connection when forced. `server.closeIdleConnections()` /
- * `closeAllConnections()` are not reliable on every runtime (Bun), so sockets are tracked here.
+ * `closeAllConnections()` are not reliable on every runtime (Bun), so sockets are tracked here. The
+ * count of requests in progress lives on the socket, and one shared `close` listener per response
+ * decrements it (no closure, no map lookup per request).
  */
 export class ConnectionTracker {
-  /** Socket → number of requests in progress. */
-  readonly #sockets = new Map<Socket, number>()
+  readonly #sockets = new Set<TrackedSocket>()
   #closing = false
 
-  constructor(server: Server) {
-    server.on('connection', (socket: Socket) => {
-      this.#sockets.set(socket, 0)
+  /**
+   * `requests: false` when the caller's own `request` listener calls {@link track} for every request
+   * of the server (one listener less to call per request).
+   */
+  constructor(server: Server, options: { readonly requests?: boolean } = {}) {
+    server.on('connection', (socket: TrackedSocket) => {
+      socket[TRACKER] = this
+      socket[ACTIVE] = 0
+      this.#sockets.add(socket)
       socket.once('close', () => this.#sockets.delete(socket))
     })
-    server.on('request', (request: IncomingMessage, response: ServerResponse) => {
-      const socket = request.socket
-      if (!this.#sockets.has(socket)) return
-      this.#sockets.set(socket, (this.#sockets.get(socket) ?? 0) + 1)
-      response.once('close', () => {
-        const active = this.#sockets.get(socket)
-        if (active === undefined) return
-        this.#sockets.set(socket, active - 1)
-        if (active - 1 === 0 && this.#closing) socket.end()
-      })
-    })
+    if (options.requests !== false) {
+      server.on('request', (request: IncomingMessage, response: ServerResponse) => this.track(request, response))
+    }
+  }
+
+  /** Counts a request in progress on its connection, until its response closes (other servers' requests are ignored). */
+  track(request: IncomingMessage, response: ServerResponse): void {
+    const socket = request.socket as TrackedSocket | null
+    if (socket?.[TRACKER] !== this) return
+    socket[ACTIVE] = (socket[ACTIVE] ?? 0) + 1
+    response.on('close', ConnectionTracker.#onResponseClose)
+  }
+
+  /** A response closed (`this`): one request less on its socket, ended when idle while closing. */
+  static readonly #onResponseClose = function (this: ServerResponse): void {
+    // the socket of a finished response is detached: reach it through its request
+    const socket = (this.req as IncomingMessage | undefined)?.socket as TrackedSocket | null | undefined
+    const tracker = socket?.[TRACKER]
+    if (socket == null || tracker === undefined) return
+    const active = (socket[ACTIVE] ?? 1) - 1
+    socket[ACTIVE] = active
+    if (active === 0 && tracker.#closing) socket.end()
   }
 
   /** Ends idle connections now and the others once their requests completed. */
   closeIdle(): void {
     this.#closing = true
-    for (const [socket, active] of this.#sockets) if (active === 0) socket.end()
+    for (const socket of this.#sockets) if (socket[ACTIVE] === 0) socket.end()
   }
 
   /** Destroys every connection. */
   destroyAll(): void {
     this.#closing = true
-    for (const socket of this.#sockets.keys()) socket.destroy()
+    for (const socket of this.#sockets) socket.destroy()
   }
 }
 

package/src/adapters/node.ts

@@ -82,6 +82,8 @@ class NodeHttpAdapter implements NodeAdapter {
   }
 
   readonly handler = (request: IncomingMessage, response: ServerResponse): void => {
+    // the listening server's connections (a request of another server is ignored)
+    this.#tracker?.track(request, response)
     const url = request.url ?? '/'
     const query = url.indexOf('?')
     const handler = this.#routes.find(request.method ?? 'GET', query === -1 ? url : url.slice(0, query))
@@ -101,7 +103,8 @@ class NodeHttpAdapter implements NodeAdapter {
   async listen(port: number, host: string): Promise<HttpServerAddress> {
     const server = this.#server ?? createServer(this.#options.serverOptions ?? {})
     this.#server = server
-    this.#tracker ??= new ConnectionTracker(server)
+    // `handler` counts the requests
+    this.#tracker ??= new ConnectionTracker(server, { requests: false })
     this.#closing = undefined
     if (!server.listeners('request').includes(this.handler)) server.on('request', this.handler)
     await new Promise<void>((resolve, reject) => {

package/src/body.ts

@@ -19,9 +19,30 @@ export interface MediaType {
   readonly charset: string | undefined
 }
 
+/**
+ * Parsed `content-type` values: an application receives a handful of them, parsed twice per request
+ * with a body (request context, then {@link parseBody}). Bounded, since clients choose the values:
+ * cleared when full.
+ */
+const MEDIA_TYPES = new Map<string, MediaType>()
+const MEDIA_TYPES_MAX = 64
+
 /** Parses a `content-type` header value (`application/json; charset=utf-8`). */
 export function parseMediaType(header: string | undefined): MediaType | undefined {
   if (header === undefined) return undefined
+  // the most common value, compared faster than hashed
+  if (header === 'application/json') return { type: 'application/json', charset: undefined }
+  const cached = MEDIA_TYPES.get(header)
+  // a fresh object, as when parsing (callers own the result)
+  if (cached !== undefined) return { type: cached.type, charset: cached.charset }
+  const media = parseUncached(header)
+  if (media === undefined) return undefined
+  if (MEDIA_TYPES.size === MEDIA_TYPES_MAX) MEDIA_TYPES.clear()
+  MEDIA_TYPES.set(header, media)
+  return { type: media.type, charset: media.charset }
+}
+
+function parseUncached(header: string): MediaType | undefined {
   const separator = header.indexOf(';')
   const type = (separator === -1 ? header : header.slice(0, separator)).trim().toLowerCase()
   if (type === '') return undefined
@@ -86,13 +107,21 @@ export function parseBody(
   contentEncoding?: string | undefined,
 ): Promise<unknown> {
   try {
-    return Promise.resolve(parseBytes(bytes, contentType, contentEncoding))
+    return Promise.resolve(parseBodyBytes(bytes, contentType, contentEncoding))
   } catch (error) {
     return Promise.reject(error)
   }
 }
 
-function parseBytes(bytes: Uint8Array, contentType: string | undefined, contentEncoding: string | undefined): unknown {
+/**
+ * {@link parseBody} without the promise: returns the parsed body or throws its `HttpException`
+ * (internal: the request context parses the buffered body with it, without an extra microtask).
+ */
+export function parseBodyBytes(
+  bytes: Uint8Array,
+  contentType: string | undefined,
+  contentEncoding: string | undefined,
+): unknown {
   if (bytes.byteLength === 0) return undefined
   checkContentEncoding(contentEncoding)
   const media = parseMediaType(contentType)

package/src/coerce.ts

@@ -60,7 +60,31 @@ function single(value: unknown, label: string): string {
   throw invalid(label, 'a string', value)
 }
 
+/** Longest run of decimal digits whose value is exact without parsing (`999999999999999` < 2^53). */
+const MAX_FAST_DIGITS = 15
+
+/**
+ * The value of `text` when it is 1 to 15 ASCII decimal digits (the common `/users/42`), `-1`
+ * otherwise. The same number as `Number(text)` for such a string, without the regular expression,
+ * the trim and the parse of the general path.
+ */
+function digitsValue(text: string): number {
+  const length = text.length
+  if (length === 0 || length > MAX_FAST_DIGITS) return -1
+  let result = 0
+  for (let index = 0; index < length; index++) {
+    const digit = text.charCodeAt(index) - 48
+    if (digit < 0 || digit > 9) return -1
+    result = result * 10 + digit
+  }
+  return result
+}
+
 function toNumber(value: unknown, label: string): number {
+  if (typeof value === 'string') {
+    const digits = digitsValue(value)
+    if (digits !== -1) return digits
+  }
   const raw = single(value, label)
   const text = raw.trim()
   if (NUMBER.test(text)) {
@@ -71,6 +95,10 @@ function toNumber(value: unknown, label: string): number {
 }
 
 function toInteger(value: unknown, label: string): number {
+  if (typeof value === 'string') {
+    const digits = digitsValue(value)
+    if (digits !== -1) return digits
+  }
   const raw = single(value, label)
   const text = raw.trim()
   if (INTEGER.test(text)) {
@@ -81,6 +109,9 @@ function toInteger(value: unknown, label: string): number {
 }
 
 function toBoolean(value: unknown, label: string): boolean {
+  // the canonical spellings, without the trim and the lower-casing of the general path
+  if (value === 'true' || value === '1') return true
+  if (value === 'false' || value === '0') return false
   const raw = single(value, label)
   switch (raw.trim().toLowerCase()) {
     case 'true':

package/src/compiler/analyze.ts

@@ -31,7 +31,7 @@ import { joinPaths, normalizePath } from '../path.ts'
 import { parseByteSize } from '../size.ts'
 import { acceptsUndefined, isRaw, parameterType, planCoercion } from './coercion.ts'
 import { Codes, HTTP_PACKAGE, Ids, PARAM_SOURCES, ROUTE_METHODS } from './model.ts'
-import { isRouteMetaDecorator, isValueRef, routeMeta } from './route-decorators.ts'
+import { isRouteMetaDecorator, isValueRef, readRouteMeta } from './route-decorators.ts'
 
 /** Name of the extension (owner of the decorators in `DecoratorInfo.owner`). */
 export const EXTENSION_NAME = 'http'
@@ -96,7 +96,7 @@ export function analyzeHttpClass(cls: ClassInfo, ctx: Context): void {
   const basePath = normalizePath(options.path)
   const guards = classRefs(ctx, cls, cls.decorators, Ids.UseGuard, 'guard')
   const interceptors = classRefs(ctx, cls, cls.decorators, Ids.UseInterceptor, 'interceptor')
-  const meta = routeMeta(ctx, cls, cls.decorators, cls.displayName)
+  const meta = readRouteMeta(ctx, cls)
   const bodyLimit = bodyLimitOf(ctx, cls.decorators)
   const routes: HttpRouteData[] = []
   for (const method of cls.methods) {
@@ -328,7 +328,7 @@ function analyzeMethod(
   let headers = responseHeaders(ctx, decorators)
   const guards = classRefs(ctx, cls, decorators, Ids.UseGuard, 'guard')
   const interceptors = classRefs(ctx, cls, decorators, Ids.UseInterceptor, 'interceptor')
-  const meta = routeMeta(ctx, cls, decorators, where)
+  const meta = readRouteMeta(ctx, cls, method)
   const bodySchema =
     bodyValidation !== undefined && !params.some(param => param.source === 'body') ? bodyValidation.schema : undefined
   let rawResponse = params.some(param => param.source === 'response')

package/src/compiler/generate.ts

@@ -30,6 +30,7 @@ const UPLOAD_HELPERS = {
 interface Helpers {
   coerce(): GenNode
   validate(): GenNode
+  isThenable(): GenNode
   uploads(): GenNode
   context(): GenNode
 }
@@ -98,6 +99,7 @@ function groupsNode(ctx: Context, controllers: readonly HttpControllerData[]): G
 function createHelpers(ctx: Context): Helpers {
   let coerce: GenNode | undefined
   let validate: GenNode | undefined
+  let isThenable: GenNode | undefined
   let uploads: GenNode | undefined
   let context: GenNode | undefined
   return {
@@ -109,6 +111,10 @@ function createHelpers(ctx: Context): Helpers {
       validate ??= ctx.importFrom(HTTP_PACKAGE, 'validate')
       return validate
     },
+    isThenable: () => {
+      isThenable ??= ctx.importFrom(HTTP_PACKAGE, 'isThenable')
+      return isThenable
+    },
     uploads: () => {
       uploads ??= ctx.importFrom(HTTP_PACKAGE, 'uploads')
       return uploads
@@ -239,39 +245,138 @@ function tokens(ctx: Context, refs: readonly ClassRef[]): GenNode {
 // -------------------------------------------------------------------------------------------------
 
 /**
- * `(c: Controller, ctx: HttpContext) => c.handler(...args)`: `async` (awaiting every `validate()`)
- * when the route validates something with a schema, synchronous otherwise.
+ * `(c: Controller, ctx: HttpContext) => c.handler(...args)`, synchronous when no argument is
+ * validated with a schema. A route validating arguments gets a block that stays synchronous as long
+ * as every `validate()` returns a value (see {@link validatingBlock}). `@Validate(S)` without
+ * `@Body()` parameter reads the body in `invoke`: that arrow is `async` and `await`s every
+ * `validate()`.
  */
 function invokeNode(ctx: Context, helpers: Helpers, controller: HttpControllerData, route: HttpRouteData): GenNode {
-  const async = route.bodySchema !== undefined || route.params.some(param => param.schema !== undefined)
   const params: [string, GenNode][] = [['c', ctx.importType(controller.identity)]]
   // `ctx` is declared only when used (generated code type-checks with `noUnusedParameters`)
   if (route.params.length > 0 || route.bodySchema !== undefined) {
     params.push(['ctx', helpers.context()])
   }
-  return ctx.arrow(
-    params,
-    (c, http) => {
-      const args: GenNode[] = []
-      for (const param of route.params) {
-        args[param.index] = argumentNode(ctx, helpers, http as GenNode, param)
+  // arguments in evaluation order (handler parameter order); a hole is passed as `undefined`
+  const slots: (HttpParamData | undefined)[] = []
+  for (const param of route.params) {
+    slots[param.index] = param
+  }
+  const bodySchema = route.bodySchema
+  if (bodySchema !== undefined) {
+    return ctx.arrow(
+      params,
+      (c, http) => {
+        const call = handlerCall(
+          ctx,
+          c,
+          route,
+          Array.from(slots, param => awaitedArgument(ctx, helpers, http as GenNode, param)),
+        )
+        // @Validate(S) without @Body() parameter: the body is validated (and discarded)
+        const body = ctx.code`await ${ctx.call(ctx.member(http as GenNode, 'parseBody'))}`
+        const check = ctx.code`await ${validation(ctx, helpers, bodySchema, body, 'body')}`
+        return ctx.code`{ ${check}; return ${call} }`
+      },
+      { async: true },
+    )
+  }
+  const last = slots.findLastIndex(param => param?.schema !== undefined)
+  return ctx.arrow(params, (c, http) =>
+    last === -1
+      ? handlerCall(
+          ctx,
+          c,
+          route,
+          Array.from(slots, param => plainArgument(ctx, helpers, http as GenNode, param)),
+        )
+      : validatingBlock(ctx, helpers, route, slots, last, c, http as GenNode),
+  )
+}
+
+/** `c.handler(args)`. */
+function handlerCall(ctx: Context, c: GenNode, route: HttpRouteData, args: readonly GenNode[]): GenNode {
+  return ctx.call(ctx.member(c, route.handler), args)
+}
+
+/**
+ * The body of the `invoke` of a route validating arguments with schemas: the arguments up to the
+ * last validated one are evaluated in order into `const`s (`a<index>`), the handler is called with
+ * them. `validate()` returns the value when the schema validates synchronously (Zod, Valibot and
+ * ArkType without async refinements), so the request needs no promise; when one returns a
+ * thenable, the rest runs in an `async` arrow that awaits it, then evaluates the remaining arguments
+ * (`await`ing their validations) and calls the handler: the order of evaluation, the error reported
+ * when several arguments are invalid and the value received by the handler are those of an `async`
+ * `invoke` awaiting every `validate()`.
+ *
+ * ```ts
+ * (c: UserController, ctx: HttpContext) => {
+ *   const a0 = coerce.number(ctx.params['id'], 'param "id"')
+ *   const a1 = validate(UpdateUser, ctx.body, 'body')
+ *   if (isThenable(a1)) return (async () => c.update(a0, await a1, ctx))()
+ *   return c.update(a0, a1, ctx)
+ * }
+ * ```
+ */
+function validatingBlock(
+  ctx: Context,
+  helpers: Helpers,
+  route: HttpRouteData,
+  slots: readonly (HttpParamData | undefined)[],
+  last: number,
+  c: GenNode,
+  http: GenNode,
+): GenNode {
+  // `@Ctx()` and holes are inlined: nothing to evaluate
+  const bound: number[] = []
+  for (let index = 0; index <= last; index++) {
+    const param = slots[index]
+    if (param !== undefined && param.source !== 'context') {
+      bound.push(index)
+    }
+  }
+  return ctx.block(
+    bound.map(index => `a${index}`),
+    (...locals) => {
+      const local = new Map(bound.map((index, position) => [index, locals[position] as GenNode]))
+      // the value of an argument evaluated before the current statement
+      const evaluated = (index: number): GenNode => local.get(index) ?? plainArgument(ctx, helpers, http, slots[index])
+      const statements: GenNode[] = []
+      for (const index of bound) {
+        const param = slots[index] as HttpParamData
+        const name = local.get(index) as GenNode
+        statements.push(ctx.code`const ${name} = ${plainArgument(ctx, helpers, http, param)}`)
+        if (param.schema !== undefined) {
+          const rest = Array.from(slots, (other, position) => {
+            if (position < index) {
+              return evaluated(position)
+            }
+            return position === index ? ctx.code`await ${name}` : awaitedArgument(ctx, helpers, http, other)
+          })
+          const resume = ctx.arrow([], () => handlerCall(ctx, c, route, rest), { async: true })
+          statements.push(ctx.code`if (${ctx.call(helpers.isThenable(), [name])}) return (${resume})()`)
+        }
       }
-      const call = ctx.call(
-        ctx.member(c, route.handler),
-        Array.from(args, arg => arg ?? ctx.lit(undefined)),
+      const args = Array.from(slots, (param, position) =>
+        position <= last ? evaluated(position) : plainArgument(ctx, helpers, http, param),
       )
-      if (route.bodySchema === undefined) {
-        return call
-      }
-      // @Validate(S) without @Body() parameter: the body is validated (and discarded)
-      const body = ctx.code`await ${ctx.call(ctx.member(http as GenNode, 'parseBody'))}`
-      const check = validation(ctx, helpers, route.bodySchema, body, 'body')
-      return ctx.code`{ ${check}; return ${call} }`
+      statements.push(ctx.code`return ${handlerCall(ctx, c, route, args)}`)
+      return statements
     },
-    { async },
   )
 }
 
+/** An argument evaluated in an `async` arrow: its validation, if any, is `await`ed. */
+function awaitedArgument(ctx: Context, helpers: Helpers, http: GenNode, param: HttpParamData | undefined): GenNode {
+  const node = plainArgument(ctx, helpers, http, param)
+  return param?.schema === undefined ? node : ctx.code`await ${node}`
+}
+
+/** An argument as an expression (`validate()` not awaited); `undefined` for a hole. */
+function plainArgument(ctx: Context, helpers: Helpers, http: GenNode, param: HttpParamData | undefined): GenNode {
+  return param === undefined ? ctx.lit(undefined) : argumentNode(ctx, helpers, http, param)
+}
+
 /** The expression passed to the handler for one parameter. */
 function argumentNode(ctx: Context, helpers: Helpers, http: GenNode, param: HttpParamData): GenNode {
   switch (param.source) {
@@ -333,9 +438,9 @@ function argumentNode(ctx: Context, helpers: Helpers, http: GenNode, param: Http
   }
 }
 
-/** `await validate(schema, value, location)`. */
+/** `validate(schema, value, location)` (the value, or a promise when the schema validates asynchronously). */
 function validation(ctx: Context, helpers: Helpers, schema: ValueRef, value: GenNode, location: string): GenNode {
-  return ctx.code`await ${ctx.call(helpers.validate(), [ctx.ref(schema), value, location])}`
+  return ctx.call(helpers.validate(), [ctx.ref(schema), value, location])
 }
 
 /** `coerce.X(value, label, ...)`, cast with `as never` when the result does not have the declared type. */

package/src/compiler/index.ts

@@ -10,6 +10,9 @@
  * - `generate`: `metadata.extensions.http` with one `invoke` function per route (README,
  *   "Compiler contract").
  *
+ * It also exports the route decorator readers of other extensions: `readRouteMeta`,
+ * `effectiveRouteMeta` and `requiredRouteGroups`.
+ *
  * This entry only `import type`s from `@znight/compiler` and never loads the HTTP runtime.
  */
 import type { CompilerExtension, DecoratorSpec } from '@znight/compiler'
@@ -31,6 +34,16 @@ export type {
   SseRouteData,
   UploadData,
 } from './model.ts'
+export type { RequiredRouteGroup, RouteGroupMember } from './route-groups.ts'
+
+/**
+ * Route decorators for other extensions (RFC 0003 §6.4, RFC 0005 H3): read `createRouteDecorator`
+ * metadata on any class or method, and the required groups of the application, with the exact
+ * rules of controllers and routes. Stable API, see the README ("Route metadata in other
+ * extensions").
+ */
+export { effectiveRouteMeta, readRouteMeta } from './route-decorators.ts'
+export { requiredRouteGroups } from './route-groups.ts'
 
 const ROUTE: DecoratorSpec = { targets: ['method'], params: ['static'] }
 const NAME_OR_SCHEMA: DecoratorSpec = { targets: ['parameter'], params: ['value', 'value'] }