ts-procedures 3.0.1 → 3.1.0

package/src/implementations/http/express-rpc/index.test.ts

@@ -251,7 +251,7 @@ describe('ExpressRPCAppBuilder', () => {
         res.status(400).json({ customError: error.message })
       })
 
-      const builder = new ExpressRPCAppBuilder({ error: errorHandler })
+      const builder = new ExpressRPCAppBuilder({ onError: errorHandler })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
@@ -407,7 +407,10 @@ describe('ExpressRPCAppBuilder', () => {
       builder.register(RPC, factoryContext)
       const app = builder.build()
 
-      await request(app).post('/get-auth/get-auth/1').set('Authorization', 'Bearer token123').send({})
+      await request(app)
+        .post('/get-auth/get-auth/1')
+        .set('Authorization', 'Bearer token123')
+        .send({})
 
       expect(factoryContext).toHaveBeenCalledTimes(1)
       expect(factoryContext.mock.calls[0]![0]).toHaveProperty('headers')
@@ -515,7 +518,10 @@ describe('ExpressRPCAppBuilder', () => {
     })
 
     test("array scope with procedure name: ['users', 'profile'] + 'GetById' → /users/profile/get-by-id/1", () => {
-      const path = builder.makeRPCHttpRoutePath('GetById', { scope: ['users', 'profile'], version: 1 })
+      const path = builder.makeRPCHttpRoutePath('GetById', {
+        scope: ['users', 'profile'],
+        version: 1,
+      })
       expect(path).toBe('/users/profile/get-by-id/1')
     })
 
@@ -620,6 +626,231 @@ describe('ExpressRPCAppBuilder', () => {
     })
   })
 
+  // --------------------------------------------------------------------------
+  // extendProcedureDoc Tests
+  // --------------------------------------------------------------------------
+  describe('extendProcedureDoc', () => {
+    test('adds custom properties to generated documentation', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('GetUser', { scope: 'users', version: 1 }, async () => ({ name: 'test' }))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base, procedure }) => ({
+          summary: `Get user endpoint`,
+          tags: ['users'],
+          operationId: procedure.name,
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc).toHaveProperty('summary', 'Get user endpoint')
+      expect(doc).toHaveProperty('tags', ['users'])
+      expect(doc).toHaveProperty('operationId', 'GetUser')
+    })
+
+    test('receives correct base and procedure parameters', () => {
+      const extendFn = vi.fn(() => ({}))
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ id: v.string() })
+      RPC.Create(
+        'GetItem',
+        { scope: 'items', version: 2, schema: { params: paramsSchema } },
+        async () => ({})
+      )
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(1)
+      const callArg = extendFn.mock.calls[0]![0 as any] as any
+
+      // Verify base properties
+      expect(callArg.base).toHaveProperty('name', 'GetItem')
+      expect(callArg.base).toHaveProperty('version', 2)
+      expect(callArg.base).toHaveProperty('scope', 'items')
+      expect(callArg.base).toHaveProperty('path', '/items/get-item/2')
+      expect(callArg.base).toHaveProperty('method', 'post')
+      expect(callArg.base.jsonSchema).toHaveProperty('body')
+
+      // Verify procedure properties
+      expect(callArg.procedure).toHaveProperty('name', 'GetItem')
+      expect(callArg.procedure).toHaveProperty('handler')
+      expect(callArg.procedure.config).toHaveProperty('scope', 'items')
+      expect(callArg.procedure.config).toHaveProperty('version', 2)
+    })
+
+    test('base properties take precedence over extended properties', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        () => ({
+          name: 'OverriddenName',
+          path: '/overridden/path',
+          method: 'get',
+          customField: 'custom-value',
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0]!
+      // Base properties should NOT be overridden
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Custom field should be present
+      expect(doc).toHaveProperty('customField', 'custom-value')
+    })
+
+    test('different factories can have different extendProcedureDoc functions', () => {
+      const builder = new ExpressRPCAppBuilder()
+
+      const PublicRPC = Procedures<{}, RPCConfig>()
+      const AdminRPC = Procedures<{}, RPCConfig>()
+
+      PublicRPC.Create('GetPublic', { scope: 'public', version: 1 }, async () => ({}))
+      AdminRPC.Create('GetAdmin', { scope: 'admin', version: 1 }, async () => ({}))
+
+      builder
+        .register(
+          PublicRPC,
+          () => ({}),
+          () => ({
+            security: [],
+            tags: ['public'],
+          })
+        )
+        .register(
+          AdminRPC,
+          () => ({}),
+          () => ({
+            security: [{ bearerAuth: [] }],
+            tags: ['admin'],
+          })
+        )
+
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'GetPublic')!
+      const adminDoc = builder.docs.find((d) => d.name === 'GetAdmin')!
+
+      expect(publicDoc).toHaveProperty('security', [])
+      expect(publicDoc).toHaveProperty('tags', ['public'])
+      expect(adminDoc).toHaveProperty('security', [{ bearerAuth: [] }])
+      expect(adminDoc).toHaveProperty('tags', ['admin'])
+    })
+
+    test('extendProcedureDoc is called for each procedure in factory', () => {
+      const extendFn = vi.fn(() => ({ extended: true }))
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Method1', { scope: 'm1', version: 1 }, async () => ({}))
+      RPC.Create('Method2', { scope: 'm2', version: 1 }, async () => ({}))
+      RPC.Create('Method3', { scope: 'm3', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({}), extendFn)
+      builder.build()
+
+      expect(extendFn).toHaveBeenCalledTimes(3)
+
+      const procedureNames = extendFn.mock.calls.map((call: any) => call[0].procedure.name)
+      expect(procedureNames).toContain('Method1')
+      expect(procedureNames).toContain('Method2')
+      expect(procedureNames).toContain('Method3')
+    })
+
+    test('not providing extendProcedureDoc results in base documentation only', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}))
+
+      builder.register(RPC, () => ({})) // No extendProcedureDoc
+      builder.build()
+
+      const doc = builder.docs[0]!
+      expect(doc.name).toBe('Test')
+      expect(doc.path).toBe('/test/test/1')
+      expect(doc.method).toBe('post')
+      // Should not have any extra properties
+      expect(Object.keys(doc)).toEqual(['name', 'version', 'scope', 'path', 'method', 'jsonSchema'])
+    })
+
+    test('extendProcedureDoc can access procedure config for conditional logic', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('PublicEndpoint', { scope: 'public', version: 1 }, async () => ({}))
+      RPC.Create('PrivateEndpoint', { scope: 'private', version: 1 }, async () => ({}))
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ procedure }) => ({
+          isPublic: procedure.config.scope === 'public',
+          description: `This is a ${procedure.config.scope} endpoint`,
+        })
+      )
+      builder.build()
+
+      const publicDoc = builder.docs.find((d) => d.name === 'PublicEndpoint')!
+      const privateDoc = builder.docs.find((d) => d.name === 'PrivateEndpoint')!
+
+      expect(publicDoc).toHaveProperty('isPublic', true)
+      expect(publicDoc).toHaveProperty('description', 'This is a public endpoint')
+      expect(privateDoc).toHaveProperty('isPublic', false)
+      expect(privateDoc).toHaveProperty('description', 'This is a private endpoint')
+    })
+
+    test('extendProcedureDoc can use base jsonSchema for OpenAPI-style docs', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      const paramsSchema = v.object({ userId: v.string() })
+      const returnSchema = v.object({ name: v.string(), email: v.string() })
+
+      RPC.Create(
+        'GetUser',
+        { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
+        async () => ({ name: 'test', email: 'test@example.com' })
+      )
+
+      builder.register(
+        RPC,
+        () => ({}),
+        ({ base }) => ({
+          requestBody: base.jsonSchema.body
+            ? { content: { 'application/json': { schema: base.jsonSchema.body } } }
+            : undefined,
+          responses: {
+            200: base.jsonSchema.response
+              ? { content: { 'application/json': { schema: base.jsonSchema.response } } }
+              : { description: 'Success' },
+          },
+        })
+      )
+      builder.build()
+
+      const doc = builder.docs[0] as any
+      expect(doc).toHaveProperty('requestBody')
+      expect(doc.requestBody).toHaveProperty('content')
+      expect(doc).toHaveProperty('responses')
+      expect(doc.responses).toHaveProperty('200')
+    })
+  })
+
   // --------------------------------------------------------------------------
   // Integration Test
   // --------------------------------------------------------------------------

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

@@ -1,9 +1,15 @@
 import express from 'express'
 import { kebabCase } from 'es-toolkit/string'
 import { Procedures, TProcedureRegistration } from '../../../index.js'
-import { RPCConfig, RPCHttpRouteDoc } from '../../types.js'
+import {
+  ExtractConfig,
+  ExtractContext,
+  ProceduresFactory,
+  RPCConfig,
+  RPCHttpRouteDoc,
+} from '../../types.js'
 import { castArray } from 'es-toolkit/compat'
-import { ExpressFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
+import { ExpressFactoryItem } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
 
@@ -23,7 +29,14 @@ export type ExpressRPCAppBuilderConfig = {
     req: express.Request,
     res: express.Response
   ) => void
-  error?: (
+  /**
+   * Error handler called when a procedure throws an error.
+   * @param procedure
+   * @param req
+   * @param res
+   * @param error
+   */
+  onError?: (
     procedure: TProcedureRegistration,
     req: express.Request,
     res: express.Response,
@@ -115,7 +128,7 @@ export class ExpressRPCAppBuilder {
   private factories: ExpressFactoryItem<any>[] = []
 
   private _app: express.Express = express()
-  private _docs: RPCHttpRouteDoc[] = []
+  private _docs: (RPCHttpRouteDoc & object)[] = []
 
   get app(): express.Express {
     return this._app
@@ -130,14 +143,21 @@ export class ExpressRPCAppBuilder {
    * @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 (req) => Context, or an async function (req) => 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>
-      | ((req: express.Request) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+      | ((req: express.Request) => 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 ExpressFactoryItem<any>)
+    this.factories.push({ factory, factoryContext, extendProcedureDoc } as ExpressFactoryItem<any>)
     return this
   }
 
@@ -146,9 +166,9 @@ export class ExpressRPCAppBuilder {
    * @return express.Application
    */
   build(): express.Application {
-    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)
 
@@ -168,8 +188,8 @@ export class ExpressRPCAppBuilder {
               res.status(200)
             }
           } catch (error) {
-            if (this.config?.error) {
-              this.config.error(procedure, req, res, error as Error)
+            if (this.config?.onError) {
+              this.config.onError(procedure, req, res, error as Error)
               return
             }
             if (!res.status) {
@@ -191,14 +211,17 @@ export class ExpressRPCAppBuilder {
    * 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: ExpressFactoryItem['extendProcedureDoc']
+  ): RPCHttpRouteDoc {
     const { config } = procedure
     const path = ExpressRPCAppBuilder.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) {
@@ -208,10 +231,23 @@ export class ExpressRPCAppBuilder {
       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/express-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 express from 'express'
 
-/**
- * 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 ExpressFactoryItem<TFactory = ReturnType<typeof Procedures<any, RPCConfig>>> = {
   factory: TFactory
   factoryContext:
     | ExtractContext<TFactory>
     | ((req: express.Request) => 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>
 }