rouzer 0.0.0 → 1.0.0-beta.2

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "editor.formatOnSave": true,
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "rewrap.wrappingColumn": 80
+}

package/package.json

@@ -1,9 +1,33 @@
 {
   "name": "rouzer",
-  "version": "0.0.0",
+  "version": "1.0.0-beta.2",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": ">=4"
+  },
   "devDependencies": {
     "@alloc/prettier-config": "^1.0.0",
     "@typescript/native-preview": "7.0.0-dev.20251208.1",
-    "prettier": "^3.7.4"
+    "prettier": "^3.7.4",
+    "zod": "^4.1.13"
+  },
+  "dependencies": {
+    "@hattip/core": "^0.0.49",
+    "@remix-run/route-pattern": "^0.15.3",
+    "alien-middleware": "^0.10.2"
+  },
+  "prettier": "@alloc/prettier-config",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alloc/rouzer.git"
+  },
+  "scripts": {
+    "build": "tsgo -b tsconfig.json"
   }
-}
+}

package/readme.md

@@ -0,0 +1,93 @@
+# rouzer
+
+Type-safe routes shared by your server and client, powered by `zod/mini` (input validation + transforms), `@remix-run/route-pattern` (URL matching), and `alien-middleware` (typed middleware chaining). The router output is intended to be used with `@hattip/core` adapters.
+
+## Install
+
+```sh
+pnpm add rouzer zod
+```
+
+Everything is imported directly from `rouzer`.
+
+## Define routes (shared)
+
+```ts
+// routes.ts
+import * as z from 'zod/mini'
+import { $type, route } from 'rouzer'
+
+export const helloRoute = route('hello/:name', {
+  GET: {
+    query: z.object({
+      excited: z.optional(z.boolean()),
+    }),
+    // The response is only type-checked at compile time.
+    response: $type<{ message: string }>(),
+  },
+})
+
+export const routes = { helloRoute }
+```
+
+The following request parts can be validated with Zod:
+
+- `path`
+- `query`
+- `body`
+- `headers`
+
+Zod validation happens on both the server and client.
+
+## Server router
+
+```ts
+import { chain, createRouter } from 'rouzer'
+import { routes } from './routes'
+
+const middlewares = chain().use(ctx => {
+  // An example middleware. For more info, see https://github.com/alien-rpc/alien-middleware#readme
+  return {
+    db: postgres(ctx.env('POSTGRES_URL')),
+  }
+})
+
+export const handler = createRouter({
+  routes,
+  middlewares,
+  debug: process.env.NODE_ENV === 'development',
+})({
+  helloRoute: {
+    GET(ctx) {
+      const message = `Hello, ${ctx.params.name}${ctx.query.excited ? '!' : '.'}`
+      return { message }
+    },
+  },
+})
+```
+
+## Client wrapper
+
+```ts
+import { createClient } from 'rouzer'
+import { helloRoute } from './routes'
+
+const client = createClient({ baseURL: '/api/' })
+
+const { message } = await client.json(
+  helloRoute.GET({ path: { name: 'world' }, query: { excited: true } })
+)
+
+// If you want the Response object, use `client.request` instead.
+const response = await client.request(
+  helloRoute.GET({ path: { name: 'world' } })
+)
+
+const { message } = await response.json()
+```
+
+## Add an endpoint
+
+1. Declare it in `routes.ts` with `route(...)` and `zod/mini` schemas.
+2. Implement the handler in your router assembly with `createRouter(…)({ ... })`.
+3. Call it from the client with the generated helper via `client.json` or `client.request`.

package/src/client/index.ts

@@ -0,0 +1,70 @@
+import { shake } from '../common'
+import type { RouteRequest } from '../types'
+
+export function createClient(config: {
+  /**
+   * Base URL to use for all requests.
+   */
+  baseURL: string
+  /**
+   * Default headers to send with every request.
+   */
+  headers?: Record<string, string>
+  /**
+   * Custom handler for non-200 response to a `.json()` request. By default, the
+   * response is always parsed as JSON, regardless of the HTTP status code.
+   */
+  onJsonError?: (response: Response) => Response
+}) {
+  return {
+    config,
+    request<T extends RouteRequest>({
+      pathPattern,
+      method,
+      args: { path, query, body, headers },
+      route,
+    }: T) {
+      if (route.path) {
+        path = route.path.parse(path)
+      }
+
+      const url = new URL(pathPattern.href(path), config.baseURL)
+
+      if (route.query) {
+        query = route.query.parse(query ?? {})
+        url.search = new URLSearchParams(query).toString()
+      } else if (query) {
+        throw new Error('Unexpected query parameters')
+      }
+      if (route.body) {
+        body = route.body.parse(body !== undefined ? body : {})
+      } else if (body !== undefined) {
+        throw new Error('Unexpected body')
+      }
+
+      if (config.headers || headers) {
+        headers = {
+          ...config.headers,
+          ...(headers && shake(headers)),
+        }
+      }
+
+      if (route.headers) {
+        headers = route.headers.parse(headers) as any
+      }
+
+      return fetch(url, {
+        method,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        headers,
+      }) as Promise<Response & { json(): Promise<T['$result']> }>
+    },
+    async json<T extends RouteRequest>(request: T): Promise<T['$result']> {
+      const response = await this.request(request)
+      if (!response.ok && config.onJsonError) {
+        return config.onJsonError(response)
+      }
+      return response.json()
+    },
+  }
+}

package/src/common.ts

@@ -0,0 +1,99 @@
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapEntries
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapEntries(a, (key, value) => [value, key])
+ * // => { 1: 'a', 2: 'b', 3: 'c' }
+ * ```
+ * @version 12.1.0
+ */
+export function mapEntries<
+  TKey extends string | number | symbol,
+  TValue,
+  TNewKey extends string | number | symbol,
+  TNewValue,
+>(
+  obj: Record<TKey, TValue>,
+  toEntry: (key: TKey, value: TValue) => [TNewKey, TNewValue]
+): Record<TNewKey, TNewValue> {
+  if (!obj) {
+    return {} as Record<TNewKey, TNewValue>
+  }
+  return Object.entries(obj).reduce(
+    (acc, [key, value]) => {
+      const [newKey, newValue] = toEntry(key as TKey, value as TValue)
+      acc[newKey] = newValue
+      return acc
+    },
+    {} as Record<TNewKey, TNewValue>
+  )
+}
+
+/**
+ * Removes (shakes out) undefined entries from an object. Optional
+ * second argument shakes out values by custom evaluation.
+ *
+ * Note that non-enumerable keys are never shaken out.
+ *
+ * @see https://radashi.js.org/reference/object/shake
+ * @example
+ * ```ts
+ * const a = { a: 1, b: undefined, c: 3 }
+ * shake(a)
+ * // => { a: 1, c: 3 }
+ * ```
+ * @version 12.1.0
+ */
+export function shake<T extends object>(
+  obj: T
+): {
+  [K in keyof T]: Exclude<T[K], undefined>
+}
+
+export function shake<T extends object>(
+  obj: T,
+  filter: ((value: unknown) => boolean) | undefined
+): T
+
+export function shake<T extends object>(
+  obj: T,
+  filter: (value: unknown) => boolean = value => value === undefined
+): T {
+  if (!obj) {
+    return {} as T
+  }
+  return (Object.keys(obj) as (keyof T)[]).reduce((acc, key) => {
+    if (!filter(obj[key])) {
+      acc[key] = obj[key]
+    }
+    return acc
+  }, {} as T)
+}
+
+/**
+ * Map over all the keys to create a new object.
+ *
+ * @see https://radashi.js.org/reference/object/mapValues
+ * @example
+ * ```ts
+ * const a = { a: 1, b: 2, c: 3 }
+ * mapValues(a, (value, key) => value * 2)
+ * // => { a: 2, b: 4, c: 6 }
+ * ```
+ * @version 12.1.0
+ */
+export function mapValues<T extends object, U>(
+  obj: T,
+  mapFunc: (value: Required<T>[keyof T], key: keyof T) => U
+): { [K in keyof T]: U } {
+  return (Object.keys(obj) as (keyof T)[]).reduce(
+    (acc, key) => {
+      acc[key] = mapFunc(obj[key], key)
+      return acc
+    },
+    {} as { [K in keyof T]: U }
+  )
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export * from './route'
+export * from './server/router'
+export * from './client/index'
+export type * from './types'
+
+export * from 'alien-middleware'

package/src/route.ts

@@ -0,0 +1,44 @@
+import { RoutePattern } from '@remix-run/route-pattern'
+import { mapEntries } from './common'
+import type {
+  MutationRoute,
+  QueryRoute,
+  RouteArgs,
+  RouteFunction,
+  RouteRequest,
+  Routes,
+  Unchecked,
+} from './types'
+
+export function $type<T>() {
+  return null as unknown as Unchecked<T>
+}
+
+export function route<P extends string, T extends Routes>(path: P, routes: T) {
+  const pathPattern = new RoutePattern(path)
+  const createFetch =
+    (method: string, route: QueryRoute | MutationRoute) =>
+    (args: RouteArgs): RouteRequest => {
+      return {
+        route,
+        pathPattern,
+        method,
+        args,
+        $result: undefined!,
+      }
+    }
+
+  return Object.assign(
+    { path, pathPattern, routes },
+    mapEntries(
+      routes as Record<string, QueryRoute | MutationRoute>,
+      (method, route) => [method, createFetch(method, route)]
+    )
+  ) as unknown as {
+    path: P
+    pathPattern: RoutePattern
+    routes: T
+  } & {
+    [K in keyof T]: RouteFunction<Extract<T[K], QueryRoute | MutationRoute>>
+  }
+}

package/src/server/router.ts

@@ -0,0 +1,248 @@
+import type { AdapterRequestContext } from '@hattip/core'
+import { RoutePattern, type Params } from '@remix-run/route-pattern'
+import {
+  chain,
+  MiddlewareChain,
+  type MiddlewareContext,
+} from 'alien-middleware'
+import { mapValues } from '../common'
+import * as z from 'zod/mini'
+import type {
+  InferRouteResponse,
+  MutationRoute,
+  Promisable,
+  QueryRoute,
+  Routes,
+} from '../types'
+
+export { chain }
+
+type EmptyMiddlewareChain<TPlatform = unknown> = MiddlewareChain<{
+  initial: {
+    env: {}
+    properties: {}
+  }
+  current: {
+    env: {}
+    properties: {}
+  }
+  platform: TPlatform
+}>
+
+export type RouterConfig<
+  TRoutes extends Record<string, { path: string; routes: Routes }> = any,
+  TMiddleware extends MiddlewareChain = any,
+> = {
+  routes: TRoutes
+  middlewares?: TMiddleware
+  debug?: boolean
+}
+
+export function createRouter<
+  TRoutes extends Record<string, { path: string; routes: Routes }>,
+  TMiddleware extends MiddlewareChain = EmptyMiddlewareChain,
+>(config: { routes: TRoutes; middlewares?: TMiddleware; debug?: boolean }) {
+  const keys = Object.keys(config.routes)
+  const middlewares = config.middlewares ?? (chain() as TMiddleware)
+  const patterns = mapValues(
+    config.routes,
+    ({ path }) => new RoutePattern(path)
+  )
+
+  type RequestContext = MiddlewareContext<TMiddleware>
+
+  type RequestHandler<TArgs extends object, TResult> = (
+    context: RequestContext & TArgs
+  ) => Promisable<TResult | Response>
+
+  type InferRequestHandler<T, P extends string> = T extends QueryRoute
+    ? RequestHandler<
+        {
+          query: z.infer<T['query']>
+          params: Params<P>
+          headers: z.infer<T['headers']>
+        },
+        InferRouteResponse<T>
+      >
+    : T extends MutationRoute
+      ? RequestHandler<
+          {
+            body: z.infer<T['body']>
+            params: Params<P>
+            headers: z.infer<T['headers']>
+          },
+          InferRouteResponse<T>
+        >
+      : never
+
+  type RequestHandlers = {
+    [K in keyof TRoutes]: {
+      [M in keyof TRoutes[K]['routes']]: InferRequestHandler<
+        TRoutes[K]['routes'][M],
+        TRoutes[K]['path']
+      >
+    }
+  }
+
+  type TPlatform =
+    TMiddleware extends MiddlewareChain<infer T> ? T['platform'] : never
+
+  return (handlers: RequestHandlers) =>
+    middlewares.use(async function (
+      context: AdapterRequestContext<TPlatform> & {
+        url?: URL
+        params?: {}
+      }
+    ) {
+      const request = context.request as Request
+      const method = request.method.toUpperCase() as keyof Routes
+      const url: URL = (context.url ??= new URL(request.url))
+
+      for (let i = 0; i < keys.length; i++) {
+        const pattern = patterns[keys[i]]
+
+        const match = pattern.match(url)
+        if (!match) {
+          continue
+        }
+
+        const route = config.routes[keys[i]].routes[method]
+        if (!route) {
+          continue
+        }
+
+        if (route.headers) {
+          const error = parseHeaders(
+            context,
+            enableStringParsing(route.headers)
+          )
+          if (error) {
+            return httpClientError(error, 'Invalid request headers', config)
+          }
+        }
+
+        if (route.query) {
+          const error = parseQueryString(
+            context,
+            enableStringParsing(route.query)
+          )
+          if (error) {
+            return httpClientError(error, 'Invalid query string', config)
+          }
+        }
+
+        if (route.body) {
+          const error = await parseRequestBody(context, route.body)
+          if (error) {
+            return httpClientError(error, 'Invalid request body', config)
+          }
+        }
+
+        const handler = handlers[keys[i]][method]
+        if (!handler) {
+          continue
+        }
+
+        context.params = match.params
+
+        const result = await handler(context as any)
+        if (result instanceof Response) {
+          return result
+        }
+        return Response.json(result)
+      }
+    })
+}
+
+function httpClientError(
+  error: any,
+  message: string,
+  config: { debug?: boolean }
+) {
+  return Response.json(
+    {
+      ...error,
+      message: config.debug ? `${message}: ${error.message}` : message,
+    },
+    { status: 400 }
+  )
+}
+
+function parseHeaders(
+  context: AdapterRequestContext & { headers?: {} },
+  schema: z.ZodMiniType<any, any>
+) {
+  const headers = Object.fromEntries(context.request.headers as any)
+  const result = schema.safeParse(headers)
+  if (!result.success) {
+    return result.error
+  }
+  context.headers = result.data
+  return null
+}
+
+function parseQueryString(
+  context: AdapterRequestContext & { url?: URL; query?: {} },
+  schema: z.ZodMiniType<any, any>
+) {
+  const result = schema.safeParse(
+    Object.fromEntries(context.url!.searchParams as any)
+  )
+  if (!result.success) {
+    return result.error
+  }
+  context.query = result.data
+  return null
+}
+
+async function parseRequestBody(
+  context: AdapterRequestContext & { body?: {} },
+  schema: z.ZodMiniType<any, any>
+) {
+  const result = await context.request.json().then(
+    body => schema.safeParse(body),
+    error => ({ success: false, error }) as const
+  )
+  if (!result.success) {
+    return result.error
+  }
+  context.body = result.data
+  return null
+}
+
+const seen = new WeakMap<z.ZodMiniType<any, any>, z.ZodMiniType<any, any>>()
+
+/**
+ * Traverse object and array schemas, finding schemas that expect a number or
+ * boolean, and replace those schemas with a new schema that parses the input
+ * value as a number or boolean.
+ */
+function enableStringParsing(schema: z.ZodMiniType<any, any>): typeof schema {
+  if (schema.type === 'number') {
+    return z.pipe(z.transform(Number), schema)
+  }
+  if (schema.type === 'boolean') {
+    return z.pipe(z.transform(toBooleanStrict), schema)
+  }
+  if (schema.type === 'object') {
+    const cached = seen.get(schema)
+    if (cached) {
+      return cached
+    }
+    const modified = z.object(
+      mapValues((schema as z.ZodMiniObject<any>).def.shape, enableStringParsing)
+    )
+    seen.set(schema, modified)
+    return modified
+  }
+  if (schema.type === 'array') {
+    return z.array(
+      enableStringParsing((schema as z.ZodMiniArray<any>).def.element)
+    )
+  }
+  return schema
+}
+
+function toBooleanStrict(value: string) {
+  return value === 'true' || (value === 'false' ? false : value)
+}

package/src/types.ts

@@ -0,0 +1,89 @@
+import { Params, RoutePattern } from '@remix-run/route-pattern'
+import * as z from 'zod/mini'
+
+export type Promisable<T> = T | Promise<T>
+
+export type Unchecked<T> = { __unchecked__: T }
+
+export type QueryRoute = {
+  path?: z.ZodMiniObject<any>
+  query?: z.ZodMiniObject<any>
+  body?: never
+  headers?: z.ZodMiniObject<any>
+  response: Unchecked<any>
+}
+
+export type MutationRoute = {
+  path?: z.ZodMiniObject<any>
+  query?: never
+  body: z.ZodMiniType<any, any>
+  headers?: z.ZodMiniObject<any>
+  response?: Unchecked<any>
+}
+
+export type Routes = {
+  GET?: QueryRoute
+  POST?: MutationRoute
+  PUT?: MutationRoute
+  PATCH?: MutationRoute
+  DELETE?: MutationRoute
+}
+
+declare class Any {
+  private isAny: true
+}
+
+type PathArgs<T> = T extends { path: infer TPath extends string }
+  ? Params<TPath> extends infer TParams
+    ? {} extends TParams
+      ? { path?: TParams }
+      : { path: TParams }
+    : unknown
+  : unknown
+
+type QueryArgs<T> = T extends QueryRoute & { query: infer TQuery }
+  ? {} extends z.infer<TQuery>
+    ? { query?: z.infer<TQuery> }
+    : { query: z.infer<TQuery> }
+  : unknown
+
+type MutationArgs<T> = T extends MutationRoute & { body: infer TBody }
+  ? {} extends z.infer<TBody>
+    ? { body?: z.infer<TBody> }
+    : { body: z.infer<TBody> }
+  : unknown
+
+export type RouteArgs<T extends QueryRoute | MutationRoute = any> = ([
+  T,
+] extends [Any]
+  ? { query?: any; body?: any; path?: any }
+  : QueryArgs<T> & MutationArgs<T> & PathArgs<T>) &
+  Omit<RequestInit, 'method' | 'body' | 'headers'> & {
+    headers?: Record<string, string | undefined>
+  }
+
+export type RouteRequest<TResult = any> = {
+  route: QueryRoute | MutationRoute
+  pathPattern: RoutePattern
+  method: string
+  args: RouteArgs
+  $result: TResult
+}
+
+export type RouteResponse<TResult = any> = Response & {
+  json(): Promise<TResult>
+}
+
+export type InferRouteResponse<T extends QueryRoute | MutationRoute> =
+  T extends {
+    response: Unchecked<infer TResponse>
+  }
+    ? TResponse
+    : void
+
+export type RouteFunction<T extends QueryRoute | MutationRoute> = {
+  (args: RouteArgs<T>): RouteRequest<InferRouteResponse<T>>
+
+  $args: RouteArgs<T>
+  $response: InferRouteResponse<T>
+}

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["dom", "es2019"],
+    "target": "esnext"
+  }
+}