ts-procedures 3.0.2 → 3.1.0

package/src/implementations/http/hono-rpc/index.ts

@@ -1,9 +1,15 @@
 import { Hono, Context } from 'hono'
 import { kebabCase } from 'es-toolkit/string'
-import { Procedures, TProcedureRegistration } from '../../../index.js'
-import { RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import { TProcedureRegistration } from '../../../index.js'
+import {
+  ExtractConfig,
+  ExtractContext,
+  ProceduresFactory,
+  RPCConfig,
+  RPCHttpRouteDoc,
+} from '../../types.js'
 import { castArray } from 'es-toolkit/compat'
-import { HonoFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
+import { HonoFactoryItem } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
 
@@ -110,7 +116,7 @@ export class HonoRPCAppBuilder {
   private factories: HonoFactoryItem<any>[] = []
 
   private _app: Hono = new Hono()
-  private _docs: RPCHttpRouteDoc[] = []
+  private _docs: (RPCHttpRouteDoc & object)[] = []
 
   get app(): Hono {
     return this._app
@@ -125,14 +131,21 @@ export class HonoRPCAppBuilder {
    * @param factory - The procedure factory created by Procedures<Context, RPCConfig>()
    * @param factoryContext - The context for procedure handlers. Can be a direct value,
    *                         a sync function (c) => Context, or an async function (c) => Promise<Context>
+   * @param extendProcedureDoc - A custom function to extend the generated RPC route documentation for each procedure.
    */
   register<TFactory extends ProceduresFactory>(
     factory: TFactory,
     factoryContext:
       | ExtractContext<TFactory>
-      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+      | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+    extendProcedureDoc?: (params: {
+      /* RPC App builder base http route doc */
+      base: RPCHttpRouteDoc
+      /* Procedure registration */
+      procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+    }) => Record<string, any>
   ): this {
-    this.factories.push({ factory, factoryContext } as HonoFactoryItem<any>)
+    this.factories.push({ factory, factoryContext, extendProcedureDoc } as HonoFactoryItem<any>)
     return this
   }
 
@@ -141,9 +154,9 @@ export class HonoRPCAppBuilder {
    * @return Hono
    */
   build(): Hono {
-    this.factories.forEach(({ factory, factoryContext }) => {
+    this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
       factory.getProcedures().map((procedure: TProcedureRegistration<any, RPCConfig>) => {
-        const route = this.buildRpcHttpRouteDoc(procedure)
+        const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc)
 
         this._docs.push(route)
 
@@ -182,14 +195,17 @@ export class HonoRPCAppBuilder {
    * Generates the RPC HTTP route for the given procedure.
    * @param procedure
    */
-  private buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
+  private buildRpcHttpRouteDoc(
+    procedure: TProcedureRegistration<any, RPCConfig>,
+    extendProcedureDoc: HonoFactoryItem['extendProcedureDoc']
+  ): RPCHttpRouteDoc {
     const { config } = procedure
     const path = HonoRPCAppBuilder.makeRPCHttpRoutePath({
       name: procedure.name,
       config,
       prefix: this.config?.pathPrefix,
     })
-    const method = 'post' // RPCs use POST method
+    const method = 'post' as const // RPCs use POST method
     const jsonSchema: { body?: object; response?: object } = {}
 
     if (config.schema?.params) {
@@ -199,10 +215,23 @@ export class HonoRPCAppBuilder {
       jsonSchema.response = config.schema.returnType
     }
 
-    return {
+    const base = {
+      name: procedure.name,
+      version: config.version,
+      scope: config.scope,
       path,
       method,
       jsonSchema,
     }
+    let extendedDoc: object = {}
+
+    if (extendProcedureDoc) {
+      extendedDoc = extendProcedureDoc({ base, procedure })
+    }
+
+    return {
+      ...extendedDoc,
+      ...base,
+    }
   }
 }

package/src/implementations/http/hono-rpc/types.ts

@@ -1,33 +1,16 @@
-import { RPCConfig } from '../../types.js'
-import { Procedures } from '../../../index.js'
+import { ExtractConfig, ExtractContext, RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import { Procedures, TProcedureRegistration } from '../../../index.js'
 import { Context } from 'hono'
 
-/**
- * Extracts the TContext type from a Procedures factory return type.
- * Uses the first parameter of the handler function to infer the context type.
- */
-export type ExtractContext<TFactory> = TFactory extends {
-  getProcedures: () => Array<{ handler: (ctx: infer TContext, ...args: any[]) => any }>
-}
-  ? TContext
-  : never
-
-/**
- * Minimal structural type for a Procedures factory.
- * Uses explicit `any` types to avoid variance issues with generic constraints.
- */
-export type ProceduresFactory = {
-  getProcedures: () => Array<{
-    name: string
-    config: any
-    handler: (ctx: any, params?: any) => Promise<any>
-  }>
-  Create: (...args: any[]) => any
-}
-
 export type HonoFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
   factory: TFactory
   factoryContext:
     | ExtractContext<TFactory>
     | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  extendProcedureDoc?: (params: {
+    /* RPC App builder base http route doc */
+    base: RPCHttpRouteDoc
+    /* Procedure registration */
+    procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>
+  }) => Record<string, any>
 }

package/src/implementations/types.ts

@@ -11,7 +11,8 @@ export type FactoryItem<C> = {
   factoryContext: (req: Request) => C
 }
 
-export interface RPCHttpRouteDoc {
+export interface RPCHttpRouteDoc extends RPCConfig {
+  name: string // procedure name
   path: string
   method: 'post'
   jsonSchema: {
@@ -19,3 +20,40 @@ export interface RPCHttpRouteDoc {
     response?: object
   }
 }
+
+// ================
+// Utility types
+// ================
+
+/**
+ * Extracts the TContext type from a Procedures factory return type.
+ * Uses the first parameter of the handler function to infer the context type.
+ */
+export type ExtractContext<TFactory> = TFactory extends {
+  getProcedures: () => Array<{ handler: (ctx: infer TContext, ...args: any[]) => any }>
+}
+  ? TContext
+  : never
+
+/**
+ * Extracts the TConfig type from a Procedures factory return type.
+ * Uses the config property of the procedure registration to infer the config type.
+ */
+export type ExtractConfig<TFactory> = TFactory extends {
+  getProcedures: () => Array<{ config: infer TConfig }>
+}
+  ? TConfig
+  : never
+
+/**
+ * Minimal structural type for a Procedures factory.
+ * Uses explicit `any` types to avoid variance issues with generic constraints.
+ */
+export type ProceduresFactory = {
+  getProcedures: () => Array<{
+    name: string
+    config: any
+    handler: (ctx: any, params?: any) => Promise<any>
+  }>
+  Create: (...args: any[]) => any
+}