Support path schema

In the previous example, we allowed to pass any path parameter. Now we will reduce the possibilities to "John" and "Michelle".

Add the path parameters schema to our greet handler

The schema for that is x.literal('John', 'Michelle'), let’s enable support for that.

// src/server-first/2-support-path-schema/greet-handler.tsx

/** @jsxImportSource hono/jsx */
import { delay } from '@/utils/delay'
import * as x from 'unhoax'
import { HandlerBuilder } from './handler-builder'
import { respondWith } from '../definition/response'

export const greetHandler = HandlerBuilder.get('/hello/:name').handleWith( 
  async ({ params }) => { 
export const greetHandler = HandlerBuilder.get('/hello/:name') 
  .params({ name: x.literal('John', 'Michelle') }, () => { 
    return respondWith 
      .status(400) 
      .html(<div style="color: red">Name must be “John” or “Michelle”</div>) 
  }) 
  .handleWith(async ({ params }) => { 
    await delay(150) // mimic DB access.

    return respondWith 
      .headers({ 'x-server': 'Test' }) 
      .html(<div style="color: blue">Hello, {params.name}</div>) 
  }, 
) // [!code --]    return respondWith.html(<div style="color: blue">Hello, {params.name}</div>)
  }) 

Fixing the HandlerBuilder

// src/server-first/2-support-path-schema/handler-builder.ts

import * as x from 'unhoax'
import { PathParameters } from '../definition/PathParameters'
import { HttpMethod } from '../definition/html-route'
import { Handler, HandlerInput } from './handler'

function createHandlerBuilder(method: HttpMethod) {
  return <Path extends `/${string}`>(path: Path) => {
    let paramsGuard: GuardConfig | undefined

    const builder: HandlerBuilder<Path, PathParameters<Path>> = {
      params(props, onInvalid) { 
        paramsGuard = { schema: x.object(props), onInvalid } 
        return builder as any
      }, 

      handleWith(handle) {
        return {
          method,
          path,
          handle, 
          handle: async (input) => { 
            const params = guardWith(paramsGuard, input.params, input.params) 
            if (!params.success) return params.error 

            return handle({ 
              ...input, 
              params: params.value as any, 
            }) 
          }, 
        }
      },
    }
    return builder
  }
}

export const HandlerBuilder = {
  get: createHandlerBuilder('GET'),
  post: createHandlerBuilder('POST'),
}

interface HandlerBuilder<
  Path,
  Params,
  Query = Record<string, any>,
  Body = undefined,
> {
  params<P extends Record<string, any>>( 
    props: x.PropsOf<P>, 
    onInvalid: OnInvalid, 
  ): HandlerBuilder<Path, P, Query, Body> 

  handleWith(
    handler: (input: HandlerInput<Params, Query, Body>) => Promise<Response>,
  ): Handler<Path, Params, Query, Body>
}

type OnInvalid = (error: x.ParseError) => Response | Promise<Response> 

interface GuardConfig { 
  schema: x.Schema<unknown> 
  onInvalid: OnInvalid
} 
type GuardResult =
  | { success: false; error: ReturnType<OnInvalid> } 
  | { success: true; value: unknown } 

function guardWith<F>( 
  config: GuardConfig | undefined, 
  value: unknown, 
  fallback: F, 
): GuardResult { 
  if (!config) return { success: true, value: fallback } 
  const result = config.schema.parse(value) 
  return result.success 
    ? result 
    : { success: false, error: config.onInvalid(result.error) } 
} 

Unit testing

// src/server-first/2-support-path-schema/greet-handler.spec.ts

import { describe, expect, it } from 'vitest'
import { greetHandler } from './greet-handler'

describe('greetHandler – with params', () => {
  it('fails with 400 when params are invalid', async () => {
    const result = await greetHandler.handle({
      params: { name: 'Toto' },
      body: undefined,
      query: {},
      headers: new Headers(),
    })
    expect(result.status).toBe(400)
    expect(await result.text()).toBe(
      '<div style="color: red">Name must be “John” or “Michelle”</div>',
    )
  })

  it('responds with 200 & a blue div', async () => {
    const result = await greetHandler.handle({
      params: { name: 'John' },
      body: undefined,
      query: {},
      headers: new Headers(),
    })
    expect(result.status).toBe(200)
    expect(await result.text()).toBe(
      '<div style="color: blue">Hello, John</div>',
    )
  })
})

Result:

 ✓ server-first/2-support-path-schema/greet-handler.spec.ts (2) 507ms
   ✓ greetHandler – with params (2) 507ms
     ✓ fails with 400 when params are invalid
     ✓ responds with 200 & a blue div 501ms

End-to-End Testing

Ok we should be settled now, let’s run and test:

npx tsx ./src/server-first/2-support-path-schema/server.ts

$ curl http://localhost:6600/hello/Jack
<div style="color: red">Name must be “John” or “Michelle”</div>
# ✅

$ curl http://localhost:6600/hello/John
<div style="color: blue">Hello, John</div>
# ✅

Awesome, we have our first brick of validation!

Let’s support query parameters and body