refactor(contract, server): improve lazy, naming, hidden, ... (#214)

- Improve lazy, no need FlatLazy anymore
- Improve naming,
- Improve hidden,

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Updated the connection status header in the event iterator docs for
clearer descriptions.
- **Refactor**
- Streamlined internal routing, builder, and middleware systems to
improve type safety, error mapping, and lazy-loading performance.
- **Tests**
- Expanded test coverage to validate enhanced router and procedure
functionalities.
- Introduced new tests for `createAssertedLazyProcedure` and
`createContractedProcedure`.
- **Chores**
- Consolidated module exports and internal utilities for improved
maintainability.

These improvements maintain existing functionality while enhancing
stability and developer efficiency.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: dinwwwh

apps/content/docs/client/event-iterator.md

@@ -71,7 +71,7 @@ catch (error) {
 Errors thrown by the server can be instances of `ORPCError`.
 :::
 
-## Event Iterator Connection Status
+## Connection Status
 
 Combine with `onEventIteratorStatusChange` to track the connection status of the event iterator.
 

packages/contract/src/builder-variants.test-d.ts

@@ -3,7 +3,7 @@ import type { ContractBuilder } from './builder'
 import type { ContractProcedureBuilder, ContractProcedureBuilderWithInput, ContractProcedureBuilderWithInputOutput, ContractProcedureBuilderWithOutput, ContractRouterBuilder } from './builder-variants'
 import type { MergedErrorMap } from './error'
 import type { ContractProcedure } from './procedure'
-import type { AdaptedContractRouter } from './router'
+import type { EnhancedContractRouter } from './router-utils'
 import { type baseErrorMap, type BaseMeta, generalSchema, type inputSchema, type outputSchema, ping, pong } from '../tests/shared'
 
 const generalBuilder = {} as ContractBuilder<typeof inputSchema, typeof outputSchema, typeof baseErrorMap, BaseMeta>
@@ -311,7 +311,7 @@ describe('ContractRouterBuilder', () => {
     }
 
     expectTypeOf(builder.router(router)).toEqualTypeOf<
-      AdaptedContractRouter<typeof router, typeof baseErrorMap>
+      EnhancedContractRouter<typeof router, typeof baseErrorMap>
     >()
 
     // @ts-expect-error - invalid router

packages/contract/src/builder-variants.ts

@@ -2,7 +2,8 @@ import type { ErrorMap, MergedErrorMap } from './error'
 import type { Meta } from './meta'
 import type { ContractProcedure } from './procedure'
 import type { HTTPPath, Route } from './route'
-import type { AdaptContractRouterOptions, AdaptedContractRouter, ContractRouter } from './router'
+import type { ContractRouter } from './router'
+import type { EnhanceContractRouterOptions, EnhancedContractRouter } from './router-utils'
 import type { Schema } from './schema'
 
 export interface ContractProcedureBuilder<
@@ -101,7 +102,7 @@ export interface ContractRouterBuilder<
   TErrorMap extends ErrorMap,
   TMeta extends Meta,
 > {
-  '~orpc': AdaptContractRouterOptions<TErrorMap>
+  '~orpc': EnhanceContractRouterOptions<TErrorMap>
 
   'errors'<U extends ErrorMap>(
     errors: U,
@@ -111,5 +112,5 @@ export interface ContractRouterBuilder<
 
   'tag'(...tags: string[]): ContractRouterBuilder <TErrorMap, TMeta>
 
-  'router'<T extends ContractRouter<TMeta>>(router: T): AdaptedContractRouter <T, TErrorMap>
+  'router'<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap>
 }

packages/contract/src/builder.test-d.ts

@@ -3,7 +3,7 @@ import type { ContractBuilder } from './builder'
 import type { ContractProcedureBuilder, ContractProcedureBuilderWithInput, ContractProcedureBuilderWithOutput, ContractRouterBuilder } from './builder-variants'
 import type { MergedErrorMap } from './error'
 import type { ContractProcedure } from './procedure'
-import type { AdaptedContractRouter } from './router'
+import type { EnhancedContractRouter } from './router-utils'
 import { generalSchema, ping, pong } from '../tests/shared'
 
 const builder = {} as ContractBuilder<typeof inputSchema, typeof outputSchema, typeof baseErrorMap, BaseMeta>
@@ -135,7 +135,7 @@ describe('ContractBuilder', () => {
     }
 
     expectTypeOf(builder.router(router)).toEqualTypeOf<
-      AdaptedContractRouter<typeof router, typeof baseErrorMap>
+      EnhancedContractRouter<typeof router, typeof baseErrorMap>
     >()
 
     // @ts-expect-error - invalid router

packages/contract/src/builder.test.ts

@@ -2,9 +2,9 @@ import { baseErrorMap, baseMeta, baseRoute, generalSchema, inputSchema, outputSc
 import { ContractBuilder } from './builder'
 import { mergeErrorMap } from './error'
 import { isContractProcedure } from './procedure'
-import * as Router from './router'
+import * as RouterUtilsModule from './router-utils'
 
-const adaptContractRouterSpy = vi.spyOn(Router, 'adaptContractRouter')
+const enhanceContractRouterSpy = vi.spyOn(RouterUtilsModule, 'enhanceContractRouter')
 
 const def = {
   errorMap: baseErrorMap,
@@ -126,8 +126,8 @@ describe('contractBuilder', () => {
   it('.router', () => {
     const router = { ping, pong }
     const applied = builder.router(router)
-    expect(applied).toBe(adaptContractRouterSpy.mock.results[0]?.value)
-    expect(adaptContractRouterSpy).toHaveBeenCalledOnce()
-    expect(adaptContractRouterSpy).toHaveBeenCalledWith(router, def)
+    expect(applied).toBe(enhanceContractRouterSpy.mock.results[0]?.value)
+    expect(enhanceContractRouterSpy).toHaveBeenCalledOnce()
+    expect(enhanceContractRouterSpy).toHaveBeenCalledWith(router, def)
   })
 })

packages/contract/src/builder.ts

@@ -1,19 +1,19 @@
 import type { ContractProcedureBuilder, ContractProcedureBuilderWithInput, ContractProcedureBuilderWithOutput, ContractRouterBuilder } from './builder-variants'
 import type { ContractProcedureDef } from './procedure'
-import type { AdaptContractRouterOptions, AdaptedContractRouter, ContractRouter } from './router'
+import type { ContractRouter } from './router'
 import type { Schema } from './schema'
 import { type ErrorMap, type MergedErrorMap, mergeErrorMap } from './error'
 import { mergeMeta, type Meta } from './meta'
 import { ContractProcedure } from './procedure'
 import { type HTTPPath, mergePrefix, mergeRoute, mergeTags, type Route } from './route'
-import { adaptContractRouter } from './router'
+import { enhanceContractRouter, type EnhanceContractRouterOptions, type EnhancedContractRouter } from './router-utils'
 
 export interface ContractBuilderDef<
   TInputSchema extends Schema,
   TOutputSchema extends Schema,
   TErrorMap extends ErrorMap,
   TMeta extends Meta,
-> extends ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>, AdaptContractRouterOptions<TErrorMap> {
+> extends ContractProcedureDef<TInputSchema, TOutputSchema, TErrorMap, TMeta>, EnhanceContractRouterOptions<TErrorMap> {
 }
 
 export class ContractBuilder<
@@ -114,8 +114,8 @@ export class ContractBuilder<
     })
   }
 
-  router<T extends ContractRouter<TMeta>>(router: T): AdaptedContractRouter<T, TErrorMap> {
-    return adaptContractRouter(router, this['~orpc'])
+  router<T extends ContractRouter<TMeta>>(router: T): EnhancedContractRouter<T, TErrorMap> {
+    return enhanceContractRouter(router, this['~orpc'])
   }
 }
 

packages/contract/src/index.ts

@@ -11,6 +11,7 @@ export * from './procedure-client'
 export * from './route'
 export * from './router'
 export * from './router-client'
+export * from './router-utils'
 export * from './schema'
 
 export { ORPCError } from '@orpc/client'

packages/contract/src/route.test.ts

@@ -1,4 +1,4 @@
-import { adaptRoute, mergePrefix, mergeRoute, mergeTags, prefixRoute, unshiftTagRoute } from './route'
+import { enhanceRoute, mergePrefix, mergeRoute, mergeTags, prefixRoute, unshiftTagRoute } from './route'
 
 it('mergeRoute', () => {
   expect(mergeRoute({ path: '/api' }, { path: '/v1' })).toEqual({ path: '/v1' })
@@ -29,14 +29,14 @@ it('mergeTags', () => {
   expect(mergeTags(['tag'], ['tag', 'tag2'])).toEqual(['tag', 'tag', 'tag2'])
 })
 
-it('adaptRoute', () => {
+it('enhanceRoute', () => {
   const route = {
     path: '/api/v1',
     tags: ['tag'],
     description: 'description',
   } as const
 
-  expect(adaptRoute(route, {
+  expect(enhanceRoute(route, {
     prefix: '/adapt',
     tags: ['adapt'],
   })).toEqual({
@@ -45,21 +45,21 @@ it('adaptRoute', () => {
     description: 'description',
   })
 
-  expect(adaptRoute(route, {
+  expect(enhanceRoute(route, {
     prefix: '/adapt',
   })).toEqual({
     path: '/adapt/api/v1',
     tags: ['tag'],
     description: 'description',
   })
 
-  expect(adaptRoute(route, {
+  expect(enhanceRoute(route, {
     tags: ['adapt'],
   })).toEqual({
     path: '/api/v1',
     tags: ['adapt', 'tag'],
     description: 'description',
   })
 
-  expect(adaptRoute(route, {})).toBe(route)
+  expect(enhanceRoute(route, {})).toBe(route)
 })

packages/contract/src/route.ts

@@ -101,19 +101,19 @@ export function mergeTags(a: readonly string[] | undefined, b: readonly string[]
   return a ? [...a, ...b] : b
 }
 
-export interface AdaptRouteOptions {
+export interface EnhanceRouteOptions {
   prefix?: HTTPPath
   tags?: readonly string[]
 }
 
-export function adaptRoute(route: Route, options: AdaptRouteOptions): Route {
+export function enhanceRoute(route: Route, options: EnhanceRouteOptions): Route {
   let router = route
 
   if (options.prefix) {
     router = prefixRoute(router, options.prefix)
   }
 
-  if (options.tags) {
+  if (options.tags?.length) {
     router = unshiftTagRoute(router, options.tags)
   }
 

packages/contract/src/router-utils.test-d.ts

@@ -0,0 +1,45 @@
+import type { baseErrorMap, BaseMeta, inputSchema, outputSchema, router } from '../tests/shared'
+import type { MergedErrorMap } from './error'
+import type { Meta } from './meta'
+import type { ContractProcedure } from './procedure'
+import type { EnhancedContractRouter } from './router-utils'
+
+it('EnhancedContractRouter', () => {
+  const enhanced = {} as EnhancedContractRouter<typeof router, { INVALID: { status: number }, BASE2: { message: string } }>
+
+  expectTypeOf(enhanced.ping).toEqualTypeOf<
+    ContractProcedure<
+        typeof inputSchema,
+        typeof outputSchema,
+        MergedErrorMap<{ INVALID: { status: number }, BASE2: { message: string } }, typeof baseErrorMap>,
+        BaseMeta
+    >
+  >()
+
+  expectTypeOf(enhanced.nested.ping).toEqualTypeOf<
+    ContractProcedure<
+        typeof inputSchema,
+        typeof outputSchema,
+        MergedErrorMap<{ INVALID: { status: number }, BASE2: { message: string } }, typeof baseErrorMap>,
+        BaseMeta
+    >
+  >()
+
+  expectTypeOf(enhanced.pong).toEqualTypeOf<
+    ContractProcedure<
+      undefined,
+      undefined,
+      MergedErrorMap<{ INVALID: { status: number }, BASE2: { message: string } }, Record<never, never>>,
+      Meta
+    >
+  >()
+
+  expectTypeOf(enhanced.nested.pong).toEqualTypeOf<
+    ContractProcedure<
+      undefined,
+      undefined,
+      MergedErrorMap<{ INVALID: { status: number }, BASE2: { message: string } }, Record<never, never>>,
+      Meta
+    >
+  >()
+})