ts-procedures 5.9.1 → 5.10.2

package/src/errors.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from 'vitest'
+import {
+  ProcedureError,
+  ProcedureValidationError,
+  ProcedureRegistrationError,
+} from './errors.js'
+import { DefinitionInfo } from './stack-utils.js'
+
+describe('Error Classes', () => {
+  test('ProcedureError has correct properties', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', { code: 123 })
+
+    expect(err.name).toBe('ProcedureError')
+    expect(err.procedureName).toBe('TestProc')
+    expect(err.message).toBe('Something failed')
+    expect(err.meta).toEqual({ code: 123 })
+    expect(err instanceof Error).toBe(true)
+  })
+
+  test('ProcedureValidationError extends ProcedureError', () => {
+    const err = new ProcedureValidationError('TestProc', 'Validation failed', [])
+
+    expect(err instanceof ProcedureError).toBe(true)
+    expect(err instanceof Error).toBe(true)
+    expect(err.name).toBe('ProcedureValidationError')
+  })
+
+  test('ProcedureRegistrationError extends ProcedureError', () => {
+    const err = new ProcedureRegistrationError('TestProc', 'Registration failed')
+
+    expect(err instanceof ProcedureError).toBe(true)
+    expect(err instanceof Error).toBe(true)
+    expect(err.name).toBe('ProcedureRegistrationError')
+    expect(err.procedureName).toBe('TestProc')
+  })
+
+  test('ProcedureError supports cause property', () => {
+    const cause = new Error('Original error')
+    const err = new ProcedureError('TestProc', 'Wrapped error')
+    err.cause = cause
+
+    expect(err.cause).toBe(cause)
+  })
+
+  test('All error types have consistent procedureName property', () => {
+    const baseErr = new ProcedureError('Proc1', 'message')
+    const validationErr = new ProcedureValidationError('Proc2', 'message', [])
+    const registrationErr = new ProcedureRegistrationError('Proc3', 'message')
+
+    expect(baseErr.procedureName).toBe('Proc1')
+    expect(validationErr.procedureName).toBe('Proc2')
+    expect(registrationErr.procedureName).toBe('Proc3')
+  })
+})
+
+describe('Error Classes - Definition Info', () => {
+  const mockDefinitionInfo: DefinitionInfo = {
+    definedAt: {
+      file: '/app/procedures/user.ts',
+      line: 25,
+      column: 3,
+      raw: 'at Object.<anonymous> (/app/procedures/user.ts:25:3)',
+    },
+    definitionStack: 'Error\n    at Object.<anonymous> (/app/procedures/user.ts:25:3)',
+  }
+
+  test('ProcedureError includes definedAt when provided', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+    expect(err.definedAt?.line).toBe(25)
+    expect(err.definedAt?.column).toBe(3)
+  })
+
+  test('ProcedureError includes definitionStack when provided', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.definitionStack).toBeDefined()
+    expect(err.definitionStack).toContain('/app/procedures/user.ts')
+  })
+
+  test('ProcedureError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', { code: 123 })
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.procedureName).toBe('TestProc')
+    expect(err.message).toBe('Something failed')
+    expect(err.meta).toEqual({ code: 123 })
+  })
+
+  test('ProcedureValidationError includes definedAt when provided', () => {
+    const err = new ProcedureValidationError('TestProc', 'Validation failed', [], mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+    expect(err.definedAt?.line).toBe(25)
+  })
+
+  test('ProcedureValidationError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureValidationError('TestProc', 'Validation failed', [])
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.name).toBe('ProcedureValidationError')
+  })
+
+  test('ProcedureRegistrationError includes definedAt when provided', () => {
+    const err = new ProcedureRegistrationError('TestProc', 'Registration failed', mockDefinitionInfo)
+
+    expect(err.definedAt).toBeDefined()
+    expect(err.definedAt?.file).toBe('/app/procedures/user.ts')
+  })
+
+  test('ProcedureRegistrationError works without definitionInfo (backward compat)', () => {
+    const err = new ProcedureRegistrationError('TestProc', 'Registration failed')
+
+    expect(err.definedAt).toBeUndefined()
+    expect(err.definitionStack).toBeUndefined()
+    expect(err.name).toBe('ProcedureRegistrationError')
+  })
+
+  test('getDefinitionLocation returns formatted location string', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    const location = err.getDefinitionLocation()
+
+    expect(location).toBe('/app/procedures/user.ts:25:3')
+  })
+
+  test('getDefinitionLocation returns undefined when no definedAt', () => {
+    const err = new ProcedureError('TestProc', 'Something failed')
+
+    const location = err.getDefinitionLocation()
+
+    expect(location).toBeUndefined()
+  })
+
+  test('enhanced stack contains definition location', () => {
+    const err = new ProcedureError('TestProc', 'Something failed', undefined, mockDefinitionInfo)
+
+    expect(err.stack).toContain('--- Procedure "TestProc" defined at ---')
+    expect(err.stack).toContain('/app/procedures/user.ts:25:3')
+  })
+
+  test('stack is not modified when no definitionInfo', () => {
+    const err = new ProcedureError('TestProc', 'Something failed')
+
+    expect(err.stack).toBeDefined()
+    expect(err.stack).not.toContain('--- Procedure')
+  })
+
+  test('all error types enhance stack with definition location', () => {
+    const baseErr = new ProcedureError('Proc1', 'message', undefined, mockDefinitionInfo)
+    const validationErr = new ProcedureValidationError('Proc2', 'message', [], mockDefinitionInfo)
+    const registrationErr = new ProcedureRegistrationError('Proc3', 'message', mockDefinitionInfo)
+
+    expect(baseErr.stack).toContain('--- Procedure "Proc1" defined at ---')
+    expect(validationErr.stack).toContain('--- Procedure "Proc2" defined at ---')
+    expect(registrationErr.stack).toContain('--- Procedure "Proc3" defined at ---')
+  })
+})

package/src/errors.ts

@@ -0,0 +1,107 @@
+import { TSchemaValidationError } from './schema/parser.js'
+import { DefinitionInfo, DefinitionLocation, formatDefinitionInfo } from './stack-utils.js'
+import { kebabCase } from 'es-toolkit/string'
+
+export class ProcedureError extends Error {
+  cause?: unknown
+  readonly definedAt?: DefinitionLocation
+  readonly definitionStack?: string
+
+  constructor(
+    readonly procedureName: string,
+    readonly message: string,
+    readonly meta?: object,
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    super(message)
+    this.name = 'ProcedureError'
+
+    if (definitionInfo) {
+      this.definedAt = definitionInfo.definedAt
+      this.definitionStack = definitionInfo.definitionStack
+      this.enhanceStack()
+    }
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureError.prototype)
+  }
+
+  /**
+   * Returns a formatted string showing where the procedure was defined.
+   */
+  getDefinitionLocation(): string | undefined {
+    if (!this.definedAt) {
+      return undefined
+    }
+    return `${this.definedAt.file}:${this.definedAt.line}:${this.definedAt.column}`
+  }
+
+  /**
+   * Enhances the error stack with definition location information.
+   */
+  private enhanceStack(): void {
+    if (!this.stack || !this.definedAt) {
+      return
+    }
+
+    const definitionSection = formatDefinitionInfo(
+      { definedAt: this.definedAt, definitionStack: this.definitionStack },
+      this.procedureName
+    )
+
+    if (definitionSection) {
+      this.stack = this.stack + definitionSection
+    }
+  }
+}
+
+export class ProcedureValidationError extends ProcedureError {
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    readonly errors?: TSchemaValidationError[],
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    const readableErrors = errors
+      ?.map((err) => `- ${kebabCase(err.instancePath).replace('-', '.')} ${err.message}`)
+      .join(', ')
+    super(procedureName, message + ' ' + readableErrors, { errors }, definitionInfo)
+    this.name = 'ProcedureValidationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureValidationError.prototype)
+  }
+}
+
+export class ProcedureRegistrationError extends ProcedureError {
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    super(procedureName, message, undefined, definitionInfo)
+    this.name = 'ProcedureRegistrationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureRegistrationError.prototype)
+  }
+}
+
+export class ProcedureYieldValidationError extends ProcedureError {
+  constructor(
+    readonly procedureName: string,
+    message: string,
+    readonly errors?: TSchemaValidationError[],
+    // Used for error stack trace details
+    definitionInfo?: DefinitionInfo
+  ) {
+    super(procedureName, message, undefined, definitionInfo)
+    this.name = 'ProcedureYieldValidationError'
+
+    // https://www.dannyguo.com/blog/how-to-fix-instanceof-not-working-for-custom-errors-in-typescript/
+    Object.setPrototypeOf(this, ProcedureYieldValidationError.prototype)
+  }
+}

package/src/exports.ts

@@ -0,0 +1,7 @@
+export * from './index.js'
+export * from './errors.js'
+export * from './stack-utils.js'
+export * from './schema/extract-json-schema.js'
+export * from './schema/parser.js'
+export * from './schema/resolve-schema-lib.js'
+export * from './schema/types.js'

package/src/implementations/http/doc-registry.test.ts

@@ -0,0 +1,415 @@
+import { describe, expect, it, test } from 'vitest'
+import { v } from 'suretype'
+import { Procedures } from '../../index.js'
+import { HonoRPCAppBuilder } from './hono-rpc/index.js'
+import { DocRegistry } from './doc-registry.js'
+import type {
+  AnyHttpRouteDoc,
+  RPCHttpRouteDoc,
+  RPCConfig,
+  APIHttpRouteDoc,
+  StreamHttpRouteDoc,
+  DocSource,
+  DocEnvelope,
+} from '../types.js'
+
+// ---------------------------------------------------------------------------
+// Helpers — minimal doc fixtures
+// ---------------------------------------------------------------------------
+
+const rpcDoc: RPCHttpRouteDoc = {
+  kind: 'rpc',
+  name: 'Echo',
+  path: '/echo/1',
+  method: 'post',
+  scope: 'echo',
+  version: 1,
+  jsonSchema: { body: { type: 'object' } },
+}
+
+const apiDoc: APIHttpRouteDoc = {
+  kind: 'api',
+  name: 'GetUser',
+  path: '/users/:id',
+  method: 'get',
+  fullPath: '/api/users/:id',
+  jsonSchema: { pathParams: { type: 'object' } },
+}
+
+const streamDoc: StreamHttpRouteDoc = {
+  kind: 'stream',
+  name: 'Feed',
+  path: '/feed/1',
+  methods: ['get'],
+  streamMode: 'sse',
+  scope: 'feed',
+  version: 1,
+  jsonSchema: { yieldType: { type: 'object' } },
+}
+
+function makeSource<T extends AnyHttpRouteDoc>(docs: T[]): DocSource<T> {
+  return { docs }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('DocRegistry', () => {
+  // --------------------------------------------------------------------------
+  // Constructor
+  // --------------------------------------------------------------------------
+  describe('constructor', () => {
+    test('uses defaults when no config provided', () => {
+      const registry = new DocRegistry()
+      const out = registry.toJSON()
+      expect(out.basePath).toBe('')
+      expect(out.headers).toEqual([])
+      expect(out.errors).toEqual([])
+    })
+
+    test('accepts partial config', () => {
+      const registry = new DocRegistry({ basePath: '/v1' })
+      const out = registry.toJSON()
+      expect(out.basePath).toBe('/v1')
+      expect(out.headers).toEqual([])
+      expect(out.errors).toEqual([])
+    })
+
+    test('accepts full config', () => {
+      const headers = [{ name: 'Authorization', description: 'Bearer token', required: true }]
+      const errors = [{ name: 'Unauthorized', statusCode: 401, description: 'Missing token' }]
+      const registry = new DocRegistry({ basePath: '/api', headers, errors })
+      const out = registry.toJSON()
+      expect(out.basePath).toBe('/api')
+      expect(out.headers).toEqual(headers)
+      expect(out.errors).toEqual(errors)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // from()
+  // --------------------------------------------------------------------------
+  describe('from()', () => {
+    test('returns this for chaining', () => {
+      const registry = new DocRegistry()
+      const result = registry.from(makeSource([rpcDoc]))
+      expect(result).toBe(registry)
+    })
+
+    test('accepts RPC builder source', () => {
+      const registry = new DocRegistry().from(makeSource([rpcDoc]))
+      expect(registry.toJSON().routes).toEqual([rpcDoc])
+    })
+
+    test('accepts API builder source', () => {
+      const registry = new DocRegistry().from(makeSource([apiDoc]))
+      expect(registry.toJSON().routes).toEqual([apiDoc])
+    })
+
+    test('accepts Stream builder source', () => {
+      const registry = new DocRegistry().from(makeSource([streamDoc]))
+      expect(registry.toJSON().routes).toEqual([streamDoc])
+    })
+
+    test('accepts plain { docs } object', () => {
+      const plain = { docs: [rpcDoc, apiDoc] }
+      const registry = new DocRegistry().from(plain)
+      expect(registry.toJSON().routes).toHaveLength(2)
+    })
+
+    test('builder not yet built returns empty routes', () => {
+      const emptySource = makeSource<RPCHttpRouteDoc>([])
+      const registry = new DocRegistry().from(emptySource)
+      expect(registry.toJSON().routes).toEqual([])
+    })
+
+    test('same builder twice duplicates routes', () => {
+      const source = makeSource([rpcDoc])
+      const registry = new DocRegistry().from(source).from(source)
+      expect(registry.toJSON().routes).toHaveLength(2)
+      expect(registry.toJSON().routes[0]).toEqual(registry.toJSON().routes[1])
+    })
+
+    test('reads docs lazily at toJSON() time', () => {
+      const mutableDocs: RPCHttpRouteDoc[] = []
+      const source: DocSource<RPCHttpRouteDoc> = { get docs() { return mutableDocs } }
+      const registry = new DocRegistry().from(source)
+
+      expect(registry.toJSON().routes).toHaveLength(0)
+
+      mutableDocs.push(rpcDoc)
+      expect(registry.toJSON().routes).toHaveLength(1)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // toJSON()
+  // --------------------------------------------------------------------------
+  describe('toJSON()', () => {
+    test('returns correct DocEnvelope shape', () => {
+      const registry = new DocRegistry({ basePath: '/api' })
+      const out = registry.toJSON()
+      expect(out).toHaveProperty('basePath')
+      expect(out).toHaveProperty('headers')
+      expect(out).toHaveProperty('errors')
+      expect(out).toHaveProperty('routes')
+    })
+
+    test('collects routes from all sources', () => {
+      const registry = new DocRegistry()
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+        .from(makeSource([streamDoc]))
+
+      const out = registry.toJSON()
+      expect(out.routes).toHaveLength(3)
+      expect(out.routes).toEqual([rpcDoc, apiDoc, streamDoc])
+    })
+
+    test('empty when no sources', () => {
+      const out = new DocRegistry().toJSON()
+      expect(out.routes).toEqual([])
+    })
+
+    test('headers and errors are copies', () => {
+      const headers = [{ name: 'X-Custom' }]
+      const errors = [{ name: 'E', statusCode: 500, description: 'd' }]
+      const registry = new DocRegistry({ headers, errors })
+      const out = registry.toJSON()
+      expect(out.headers).toEqual(headers)
+      expect(out.headers).not.toBe(headers)
+      expect(out.errors).toEqual(errors)
+      expect(out.errors).not.toBe(errors)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // toJSON() filter
+  // --------------------------------------------------------------------------
+  describe('toJSON() filter', () => {
+    test('excludes routes by name', () => {
+      const registry = new DocRegistry()
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+
+      const out = registry.toJSON({ filter: (r) => r.name !== 'Echo' })
+      expect(out.routes).toHaveLength(1)
+      expect(out.routes[0]!.name).toBe('GetUser')
+    })
+
+    test('excludes routes by type field', () => {
+      const registry = new DocRegistry()
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+
+      const out = registry.toJSON({
+        filter: (r) => 'method' in r && (r as RPCHttpRouteDoc).method === 'post' && 'scope' in r,
+      })
+      expect(out.routes).toHaveLength(1)
+      expect(out.routes[0]!.name).toBe('Echo')
+    })
+
+    test('all filtered returns empty routes array', () => {
+      const registry = new DocRegistry().from(makeSource([rpcDoc]))
+      const out = registry.toJSON({ filter: () => false })
+      expect(out.routes).toEqual([])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // toJSON() transform
+  // --------------------------------------------------------------------------
+  describe('toJSON() transform', () => {
+    test('adds fields', () => {
+      const registry = new DocRegistry({ basePath: '/api' }).from(makeSource([rpcDoc]))
+      const out = registry.toJSON({
+        transform: (envelope) => ({ ...envelope, version: '2.0' }),
+      })
+      expect(out.version).toBe('2.0')
+      expect(out.basePath).toBe('/api')
+    })
+
+    test('reshapes envelope', () => {
+      const registry = new DocRegistry().from(makeSource([rpcDoc]))
+      const out = registry.toJSON({
+        transform: (envelope) => ({ count: envelope.routes.length }),
+      })
+      expect(out).toEqual({ count: 1 })
+    })
+
+    test('runs after filter', () => {
+      const registry = new DocRegistry()
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+
+      const out = registry.toJSON({
+        filter: (r) => r.name === 'Echo',
+        transform: (envelope) => ({ ...envelope, filteredCount: envelope.routes.length }),
+      })
+      expect(out.filteredCount).toBe(1)
+      expect(out.routes).toHaveLength(1)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // defaultErrors()
+  // --------------------------------------------------------------------------
+  describe('defaultErrors()', () => {
+    test('returns 4 entries', () => {
+      const errors = DocRegistry.defaultErrors()
+      expect(errors).toHaveLength(4)
+    })
+
+    test('has correct error names', () => {
+      const names = DocRegistry.defaultErrors().map((e) => e.name)
+      expect(names).toEqual([
+        'ProcedureError',
+        'ProcedureValidationError',
+        'ProcedureYieldValidationError',
+        'ProcedureRegistrationError',
+      ])
+    })
+
+    test('has correct status codes', () => {
+      const errors = DocRegistry.defaultErrors()
+      expect(errors[0]!.statusCode).toBe(500) // ProcedureError
+      expect(errors[1]!.statusCode).toBe(400) // ProcedureValidationError
+      expect(errors[2]!.statusCode).toBe(500) // ProcedureYieldValidationError
+      expect(errors[3]!.statusCode).toBe(500) // ProcedureRegistrationError
+    })
+
+    test('each entry has schema', () => {
+      for (const err of DocRegistry.defaultErrors()) {
+        expect(err.schema).toBeDefined()
+        expect(err.schema!.type).toBe('object')
+      }
+    })
+
+    test('returns a new array each call', () => {
+      const a = DocRegistry.defaultErrors()
+      const b = DocRegistry.defaultErrors()
+      expect(a).not.toBe(b)
+      expect(a).toEqual(b)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // kind discriminant
+  // --------------------------------------------------------------------------
+  describe('kind discriminant', () => {
+    it('rpcDoc fixture requires kind field', () => {
+      const doc = rpcDoc
+      expect(doc.kind).toBe('rpc')
+    })
+
+    it('apiDoc fixture requires kind field', () => {
+      const doc = apiDoc
+      expect(doc.kind).toBe('api')
+    })
+
+    it('streamDoc fixture requires kind field', () => {
+      const doc = streamDoc
+      expect(doc.kind).toBe('stream')
+    })
+
+    it('narrows AnyHttpRouteDoc union via kind', () => {
+      const routes: AnyHttpRouteDoc[] = [rpcDoc, apiDoc, streamDoc]
+      for (const route of routes) {
+        expect(route.kind).toBeDefined()
+      }
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Integration
+  // --------------------------------------------------------------------------
+  describe('integration', () => {
+    test('multiple builder types composed', () => {
+      const registry = new DocRegistry({
+        basePath: '/api',
+        headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
+        errors: DocRegistry.defaultErrors(),
+      })
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+        .from(makeSource([streamDoc]))
+
+      const out = registry.toJSON()
+      expect(out.basePath).toBe('/api')
+      expect(out.headers).toHaveLength(1)
+      expect(out.errors).toHaveLength(4)
+      expect(out.routes).toHaveLength(3)
+    })
+
+    test('filter + transform combined', () => {
+      const registry = new DocRegistry({
+        basePath: '/api',
+        errors: DocRegistry.defaultErrors(),
+      })
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+        .from(makeSource([streamDoc]))
+
+      const out = registry.toJSON({
+        filter: (r) => r.name !== 'Feed',
+        transform: (envelope) => ({
+          ...envelope,
+          generatedAt: '2026-01-01',
+        }),
+      })
+
+      expect(out.routes).toHaveLength(2)
+      expect(out.routes.map((r: AnyHttpRouteDoc) => r.name)).toEqual(['Echo', 'GetUser'])
+      expect(out.generatedAt).toBe('2026-01-01')
+    })
+
+    test('output is JSON.stringify-safe', () => {
+      const registry = new DocRegistry({
+        basePath: '/api',
+        headers: [{ name: 'X-Request-Id', example: 'abc-123' }],
+        errors: DocRegistry.defaultErrors(),
+      })
+        .from(makeSource([rpcDoc]))
+        .from(makeSource([apiDoc]))
+
+      const out = registry.toJSON()
+      const str = JSON.stringify(out)
+      expect(() => JSON.parse(str)).not.toThrow()
+      expect(JSON.parse(str)).toEqual(out)
+    })
+
+    test('JSON.stringify(registry) produces default envelope', () => {
+      const registry = new DocRegistry({ basePath: '/api' })
+        .from(makeSource([rpcDoc]))
+
+      const str = JSON.stringify(registry)
+      const parsed = JSON.parse(str)
+      expect(parsed.basePath).toBe('/api')
+      expect(parsed.routes).toHaveLength(1)
+      expect(parsed.routes[0].name).toBe('Echo')
+    })
+
+    test('accepts a real HonoRPCAppBuilder as source', () => {
+      const RPC = Procedures<{ userId: string }, RPCConfig>()
+
+      RPC.Create(
+        'Ping',
+        { scope: 'ping', version: 1, schema: { params: v.object({ msg: v.string() }) } },
+        async (_ctx, params) => params,
+      )
+
+      const builder = new HonoRPCAppBuilder()
+      builder.register(RPC, () => ({ userId: '123' }))
+      builder.build()
+
+      const registry = new DocRegistry({ basePath: '/rpc' }).from(builder)
+      const out = registry.toJSON()
+
+      expect(out.basePath).toBe('/rpc')
+      expect(out.routes).toHaveLength(1)
+      expect(out.routes[0]!.name).toBe('Ping')
+      expect(out.routes[0]!).toHaveProperty('jsonSchema')
+    })
+  })
+})