feat(server): lazy router/procedure (#43)

* lazy

* router caller and builder

* orpc fetch handler

* lazy for implementers

* back to old prefix

* openapi handler for lazy

* strict implementers

* openapi support lazy

* client + react

* docs

Author: dinwwwh

apps/content/content/docs/server/lazy.mdx

@@ -0,0 +1,42 @@
+---
+title: Lazy Router
+description: Enhance the performance of your oRPC router with lazy-loaded routers.
+---
+
+Enhance the performance of your oRPC router with lazy-loaded routers.
+Lazy routers in oRPC allow you to defer the loading of specific router modules until they're actually needed. 
+This can improve startup times and optimize resource usage, especially for large applications.
+
+
+## Overview 
+
+```typescript twoslash
+import { os } from '@orpc/server'
+
+const pub = os.context<{ user?: { id: string } }>()
+
+// Define a router with lazy loading
+const router = pub.router({
+    lazy: pub.lazy(() => import('examples/server')) // Lazy-load the 'examples/server' router
+})
+
+// Use the lazy-loaded router as if it were a regular one
+const output = await router.lazy.getting({ name: 'unnoq' })
+```
+
+### Key Points:
+1. **Export Requirement:**  
+   The `examples/server.ts` file must export a router as the default export. Example:  
+   ```typescript
+   import { os } from '@orpc/server'
+
+   export default os.router({
+       // something
+   })
+   ```
+
+2. **Seamless Functionality:**  
+   Once the lazy router is loaded, it behaves exactly like a standard router. You don't need to configure anything extra or worry about limitations.
+
+
+By using lazy routers, you can keep your application modular and efficient while maintaining the same user-friendly API you're used to.

apps/content/content/docs/server/meta.json

@@ -6,6 +6,7 @@
     "context",
     "contract",
     "file-upload",
+    "lazy",
     "server-action",
     "caller",
     "error-handling",

apps/content/examples/server.ts

@@ -123,3 +123,5 @@ server.listen(3000, () => {
 
 //
 //
+
+export default router

packages/client/src/router.ts

@@ -5,7 +5,7 @@ import type {
   ContractRouter,
   SchemaOutput,
 } from '@orpc/contract'
-import type { Procedure, Router } from '@orpc/server'
+import type { Lazy, Procedure, Router } from '@orpc/server'
 import type { Promisable } from '@orpc/shared'
 import { createProcedureClient, type ProcedureClient } from './procedure'
 
@@ -21,13 +21,9 @@ export type RouterClientWithContractRouter<TRouter extends ContractRouter> = {
 }
 
 export type RouterClientWithRouter<TRouter extends Router<any>> = {
-  [K in keyof TRouter]: TRouter[K] extends Procedure<
-    any,
-    any,
-    infer UInputSchema,
-    infer UOutputSchema,
-    infer UFuncOutput
-  >
+  [K in keyof TRouter]: TRouter[K] extends
+  | Procedure<any, any, infer UInputSchema, infer UOutputSchema, infer UFuncOutput>
+  | Lazy<Procedure<any, any, infer UInputSchema, infer UOutputSchema, infer UFuncOutput>>
     ? ProcedureClient<UInputSchema, UOutputSchema, UFuncOutput>
     : TRouter[K] extends Router<any>
       ? RouterClientWithRouter<TRouter[K]>

packages/contract/src/procedure.ts

@@ -35,6 +35,8 @@ export class ContractProcedure<
   ) {}
 }
 
+export type WELL_CONTRACT_PROCEDURE = ContractProcedure<Schema, Schema>
+
 export class DecoratedContractProcedure<
   TInputSchema extends Schema,
   TOutputSchema extends Schema,

packages/contract/src/router-builder.ts

@@ -3,7 +3,11 @@ import type { HTTPPath } from './types'
 import { DecoratedContractProcedure, isContractProcedure } from './procedure'
 
 export class ContractRouterBuilder {
-  constructor(public zz$crb: { prefix?: HTTPPath, tags?: string[] }) {}
+  constructor(public zz$crb: { prefix?: HTTPPath, tags?: string[] }) {
+    if (zz$crb.prefix && zz$crb.prefix.includes('{')) {
+      throw new Error('Prefix cannot contain "{" for dynamic routing')
+    }
+  }
 
   prefix(prefix: HTTPPath): ContractRouterBuilder {
     return new ContractRouterBuilder({

packages/openapi/src/fetch/base-handler.ts

@@ -1,20 +1,23 @@
 /// <reference lib="dom" />
 
 import type { HTTPPath } from '@orpc/contract'
+import type { ANY_LAZY_PROCEDURE, ANY_PROCEDURE, Router } from '@orpc/server'
 import type { FetchHandler } from '@orpc/server/fetch'
 import type { Router as HonoRouter } from 'hono/router'
+import type { EachContractLeafResultItem, EachLeafOptions } from '../utils'
 import { ORPC_HEADER, standardizeHTTPPath } from '@orpc/contract'
-import { createProcedureCaller, isProcedure, ORPCError, type Procedure, type Router, type WELL_DEFINED_PROCEDURE } from '@orpc/server'
+import { createProcedureCaller, isLazy, isProcedure, LAZY_LOADER_SYMBOL, LAZY_ROUTER_PREFIX_SYMBOL, ORPCError } from '@orpc/server'
 import { isPlainObject, mapValues, trim, value } from '@orpc/shared'
 import { OpenAPIDeserializer, OpenAPISerializer, zodCoerce } from '@orpc/transformer'
+import { eachContractProcedureLeaf } from '../utils'
 
-export type ResolveRouter = (router: Router<any>, method: string, pathname: string) => {
+export type ResolveRouter = (router: Router<any>, method: string, pathname: string) => Promise<{
   path: string[]
-  procedure: Procedure<any, any, any, any, any>
+  procedure: ANY_PROCEDURE | ANY_LAZY_PROCEDURE
   params: Record<string, string>
-} | undefined
+} | undefined>
 
-type Routing = HonoRouter<[string[], Procedure<any, any, any, any, any>]>
+type Routing = HonoRouter<string[]>
 
 export function createOpenAPIHandler(createHonoRouter: () => Routing): FetchHandler {
   const resolveRouter = createResolveRouter(createHonoRouter)
@@ -37,14 +40,21 @@ export function createOpenAPIHandler(createHonoRouter: () => Routing): FetchHand
           : undefined
       const method = customMethod || options.request.method
 
-      const match = resolveRouter(options.router, method, pathname)
+      const match = await resolveRouter(options.router, method, pathname)
 
       if (!match) {
         throw new ORPCError({ code: 'NOT_FOUND', message: 'Not found' })
       }
-      const procedure = match.procedure
+      const procedure = isLazy(match.procedure) ? (await match.procedure[LAZY_LOADER_SYMBOL]()).default : match.procedure
       const path = match.path
 
+      if (!isProcedure(procedure)) {
+        throw new ORPCError({
+          code: 'NOT_FOUND',
+          message: 'Not found',
+        })
+      }
+
       const params = procedure.zz$p.contract.zz$cp.InputSchema
         ? zodCoerce(
           procedure.zz$p.contract.zz$cp.InputSchema,
@@ -107,37 +117,65 @@ export function createOpenAPIHandler(createHonoRouter: () => Routing): FetchHand
 }
 
 const routingCache = new Map<Router<any>, Routing>()
+const pendingCache = new Map<Router<any>, { ref: EachContractLeafResultItem[] }> ()
 
 export function createResolveRouter(createHonoRouter: () => Routing): ResolveRouter {
-  return (router: Router<any>, method: string, pathname: string) => {
-    let routing = routingCache.get(router)
-
-    if (!routing) {
-      routing = createHonoRouter()
-
-      const addRouteRecursively = (routing: Routing, router: Router<any>, basePath: string[]) => {
-        for (const key in router) {
-          const currentPath = [...basePath, key]
-          const item = router[key] as WELL_DEFINED_PROCEDURE | Router<any>
-
-          if (isProcedure(item)) {
-            const method = item.zz$p.contract.zz$cp.method ?? 'POST'
-            const path = item.zz$p.contract.zz$cp.path
-              ? openAPIPathToRouterPath(item.zz$p.contract.zz$cp.path)
-              : `/${currentPath.map(encodeURIComponent).join('/')}`
-
-            routing.add(method, path, [currentPath, item])
-          }
-          else {
-            addRouteRecursively(routing, item, currentPath)
-          }
-        }
+  const addRoutes = (routing: Routing, pending: { ref: EachContractLeafResultItem[] }, options: EachLeafOptions) => {
+    const lazies = eachContractProcedureLeaf(options, ({ path, contract }) => {
+      const method = contract.zz$cp.method ?? 'POST'
+      const httpPath = contract.zz$cp.path
+        ? openAPIPathToRouterPath(contract.zz$cp.path)
+        : `/${path.map(encodeURIComponent).join('/')}`
+
+      routing.add(method, httpPath, path)
+    })
+
+    pending.ref.push(...lazies)
+  }
+
+  return async (router: Router<any>, method: string, pathname: string) => {
+    const pending = (() => {
+      let pending = pendingCache.get(router)
+      if (!pending) {
+        pending = { ref: [] }
+        pendingCache.set(router, pending)
+      }
+
+      return pending
+    })()
+
+    const routing = (() => {
+      let routing = routingCache.get(router)
+
+      if (!routing) {
+        routing = createHonoRouter()
+        routingCache.set(router, routing)
+        addRoutes(routing, pending, { router, path: [] })
+      }
+
+      return routing
+    })()
+
+    const newPending = []
+
+    for (const item of pending.ref) {
+      if (
+        (LAZY_ROUTER_PREFIX_SYMBOL in item.lazy)
+        && item.lazy[LAZY_ROUTER_PREFIX_SYMBOL]
+        && !pathname.startsWith(item.lazy[LAZY_ROUTER_PREFIX_SYMBOL] as HTTPPath)
+        && !pathname.startsWith(`/${item.path.map(encodeURIComponent).join('/')}`)
+      ) {
+        newPending.push(item)
+        continue
       }
 
-      addRouteRecursively(routing, router, [])
-      routingCache.set(router, routing)
+      const router = (await item.lazy[LAZY_LOADER_SYMBOL]()).default
+
+      addRoutes(routing, pending, { path: item.path, router })
     }
 
+    pending.ref = newPending
+
     const [matches, params_] = routing.match(method, pathname)
 
     const [match] = matches.sort((a, b) => {
@@ -148,20 +186,31 @@ export function createResolveRouter(createHonoRouter: () => Routing): ResolveRou
       return undefined
     }
 
-    const path = match[0][0]
-    const procedure = match[0][1]
+    const path = match[0]
     const params = params_
       ? mapValues(
         (match as any)[1]!,
         v => params_[v as number]!,
       )
       : match[1] as Record<string, string>
 
-    return {
-      path,
-      procedure,
-      params: { ...params }, // params from hono not a normal object, so we need spread here
+    let current: Router<any> | ANY_PROCEDURE | ANY_LAZY_PROCEDURE | undefined = router
+    for (const segment of path) {
+      if ((typeof current !== 'object' && typeof current !== 'function') || !current) {
+        current = undefined
+        break
+      }
+
+      current = (current as any)[segment]
     }
+
+    return isProcedure(current) || isLazy(current)
+      ? {
+          path,
+          procedure: current,
+          params: { ...params }, // params from hono not a normal object, so we need spread here
+        }
+      : undefined
   }
 }
 
@@ -180,7 +229,7 @@ function mergeParamsAndInput(coercedParams: Record<string, unknown>, input: unkn
   }
 }
 
-async function deserializeInput(request: Request, procedure: Procedure<any, any, any, any, any>): Promise<unknown> {
+async function deserializeInput(request: Request, procedure: ANY_PROCEDURE): Promise<unknown> {
   const deserializer = new OpenAPIDeserializer({
     schema: procedure.zz$p.contract.zz$cp.InputSchema,
   })