ts-procedures 1.1.0 → 2.0.0

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

@@ -0,0 +1,614 @@
+import { describe, expect, test, vi, beforeEach } from 'vitest'
+import request from 'supertest'
+import express from 'express'
+import { v } from 'suretype'
+import { Procedures } from '../../../index.js'
+import { ExpressRPCAppBuilder } from './index.js'
+import { RPCConfig } from '../../types.js'
+
+/**
+ * ExpressRPCAppBuilder Test Suite
+ *
+ * Tests the RPC-style Express integration for ts-procedures.
+ * This builder creates POST routes at `/rpc/{name}/{version}` paths.
+ */
+describe('ExpressRPCAppBuilder', () => {
+  // --------------------------------------------------------------------------
+  // Constructor Tests
+  // --------------------------------------------------------------------------
+  describe('constructor', () => {
+    test('creates default Express app with json middleware', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{ userId: string }, RPCConfig>()
+
+      RPC.Create(
+        'Echo',
+        { name: 'echo', version: 1, schema: { params: v.object({ message: v.string() }) } },
+        async (ctx, params) => params
+      )
+
+      builder.register(RPC, () => ({ userId: '123' }))
+      const app = builder.build()
+
+      // JSON body should be parsed automatically
+      const res = await request(app).post('/rpc/echo/1').send({ message: 'hello' })
+
+      expect(res.status).toBe(200)
+      expect(res.body).toEqual({ message: 'hello' })
+    })
+
+    test('uses provided Express app without adding middleware', async () => {
+      const customApp = express()
+      // Intentionally NOT adding json middleware
+      const builder = new ExpressRPCAppBuilder({ app: customApp })
+      const RPC = Procedures<{ userId: string }, RPCConfig>()
+
+      RPC.Create(
+        'Echo',
+        { name: 'echo', version: 1, schema: { params: v.object({ message: v.string() }) } },
+        async (ctx, params) => ({ received: params })
+      )
+
+      builder.register(RPC, () => ({ userId: '123' }))
+      const app = builder.build()
+
+      // Without json middleware, body won't be parsed (req.body is undefined)
+      const res = await request(app)
+        .post('/rpc/echo/1')
+        .set('Content-Type', 'application/json')
+        .send(JSON.stringify({ message: 'hello' }))
+
+      // Request body is undefined since json middleware wasn't added
+      // Handler receives undefined params
+      expect(res.body.received).toBeUndefined()
+    })
+
+    test('handles empty config', () => {
+      const builder = new ExpressRPCAppBuilder({})
+      expect(builder.app).toBeDefined()
+      expect(builder.docs).toEqual([])
+    })
+
+    test('handles undefined config', () => {
+      const builder = new ExpressRPCAppBuilder(undefined)
+      expect(builder.app).toBeDefined()
+      expect(builder.docs).toEqual([])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Lifecycle Hooks Tests
+  // --------------------------------------------------------------------------
+  describe('lifecycle hooks', () => {
+    test('onRequestStart is called with request object', async () => {
+      const onRequestStart = vi.fn()
+      const builder = new ExpressRPCAppBuilder({ onRequestStart })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => ({ ok: true }))
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await request(app).post('/rpc/test/1').send({})
+
+      expect(onRequestStart).toHaveBeenCalledTimes(1)
+      expect(onRequestStart.mock.calls[0]![0]).toHaveProperty('method', 'POST')
+      expect(onRequestStart.mock.calls[0]![0]).toHaveProperty('path', '/rpc/test/1')
+    })
+
+    test('onRequestEnd is called after response finishes', async () => {
+      const onRequestEnd = vi.fn()
+      const builder = new ExpressRPCAppBuilder({ onRequestEnd })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => ({ ok: true }))
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await request(app).post('/rpc/test/1').send({})
+
+      expect(onRequestEnd).toHaveBeenCalledTimes(1)
+      expect(onRequestEnd.mock.calls[0]![0]).toHaveProperty('method', 'POST')
+      expect(onRequestEnd.mock.calls[0]![1]).toHaveProperty('statusCode', 200)
+    })
+
+    test('onSuccess is called on successful procedure execution', async () => {
+      const onSuccess = vi.fn()
+      const builder = new ExpressRPCAppBuilder({ onSuccess })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => ({ ok: true }))
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await request(app).post('/rpc/test/1').send({})
+
+      expect(onSuccess).toHaveBeenCalledTimes(1)
+      expect(onSuccess.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+    })
+
+    test('onSuccess is NOT called when procedure throws', async () => {
+      const onSuccess = vi.fn()
+      const builder = new ExpressRPCAppBuilder({ onSuccess })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => {
+        throw new Error('Handler error')
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await request(app).post('/rpc/test/1').send({})
+
+      expect(onSuccess).not.toHaveBeenCalled()
+    })
+
+    test('hooks execute in correct order: start → handler → success → end', async () => {
+      const order: string[] = []
+
+      const builder = new ExpressRPCAppBuilder({
+        onRequestStart: () => order.push('start'),
+        onRequestEnd: () => order.push('end'),
+        onSuccess: () => order.push('success'),
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => {
+        order.push('handler')
+        return { ok: true }
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      await request(app).post('/rpc/test/1').send({})
+
+      expect(order).toEqual(['start', 'handler', 'success', 'end'])
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Error Handling Tests
+  // --------------------------------------------------------------------------
+  describe('error handling', () => {
+    test('custom error handler receives procedure, req, res, and error', async () => {
+      const errorHandler = vi.fn((procedure, req, res, error) => {
+        res.status(400).json({ customError: error.message })
+      })
+
+      const builder = new ExpressRPCAppBuilder({ error: errorHandler })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => {
+        throw new Error('Test error')
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await request(app).post('/rpc/test/1').send({})
+
+      expect(errorHandler).toHaveBeenCalledTimes(1)
+      expect(errorHandler.mock.calls[0]![0]).toHaveProperty('name', 'Test')
+      expect(errorHandler.mock.calls[0]![3]).toBeInstanceOf(Error)
+      expect(res.status).toBe(400)
+      // Error is wrapped by Procedures with "Error in handler for {name}" prefix
+      expect(res.body.customError).toContain('Test error')
+    })
+
+    test('default error handling returns error message in response', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => {
+        throw new Error('Something went wrong')
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await request(app).post('/rpc/test/1').send({})
+
+      // Default error handler returns error message in JSON body
+      expect(res.body).toHaveProperty('error')
+      expect(res.body.error).toContain('Something went wrong')
+    })
+
+    test('catches unhandled exceptions in handler', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => {
+        // Simulate unhandled exception
+        const obj: any = null
+        return obj.property // This will throw
+      })
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await request(app).post('/rpc/test/1').send({})
+
+      // Unhandled exceptions are caught and returned as error response
+      expect(res.body).toHaveProperty('error')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // register() Method Tests
+  // --------------------------------------------------------------------------
+  describe('register() method', () => {
+    test('returns this for method chaining', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC1 = Procedures<{}, RPCConfig>()
+      const RPC2 = Procedures<{}, RPCConfig>()
+
+      const result = builder.register(RPC1, () => ({}))
+      expect(result).toBe(builder)
+
+      // Chain multiple registrations
+      const chainResult = builder.register(RPC1, () => ({})).register(RPC2, () => ({}))
+
+      expect(chainResult).toBe(builder)
+    })
+
+    test('supports registering multiple factories', async () => {
+      const builder = new ExpressRPCAppBuilder()
+
+      const PublicRPC = Procedures<{ public: true }, RPCConfig>()
+      const PrivateRPC = Procedures<{ private: true }, RPCConfig>()
+
+      PublicRPC.Create('PublicMethod', { name: 'public', version: 1 }, async (ctx) => ({
+        isPublic: ctx.public,
+      }))
+
+      PrivateRPC.Create('PrivateMethod', { name: 'private', version: 1 }, async (ctx) => ({
+        isPrivate: ctx.private,
+      }))
+
+      builder
+        .register(PublicRPC, () => ({ public: true as const }))
+        .register(PrivateRPC, () => ({ private: true as const }))
+
+      const app = builder.build()
+
+      const publicRes = await request(app).post('/rpc/public/1').send({})
+      const privateRes = await request(app).post('/rpc/private/1').send({})
+
+      expect(publicRes.body).toEqual({ isPublic: true })
+      expect(privateRes.body).toEqual({ isPrivate: true })
+    })
+
+    test('context resolver receives Express request object', async () => {
+      const contextResolver = vi.fn((req) => ({
+        authHeader: req.headers.authorization,
+      }))
+
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{ authHeader?: string }, RPCConfig>()
+
+      RPC.Create('GetAuth', { name: 'get-auth', version: 1 }, async (ctx) => ({
+        auth: ctx.authHeader,
+      }))
+
+      builder.register(RPC, contextResolver)
+      const app = builder.build()
+
+      await request(app).post('/rpc/get-auth/1').set('Authorization', 'Bearer token123').send({})
+
+      expect(contextResolver).toHaveBeenCalledTimes(1)
+      expect(contextResolver.mock.calls[0]![0]).toHaveProperty('headers')
+      expect(contextResolver.mock.calls[0]![0].headers).toHaveProperty(
+        'authorization',
+        'Bearer token123'
+      )
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // build() Method Tests
+  // --------------------------------------------------------------------------
+  describe('build() method', () => {
+    test('creates POST routes for all procedures', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('MethodOne', { name: 'method-one', version: 1 }, async () => ({ m: 1 }))
+      RPC.Create('MethodTwo', { name: 'method-two', version: 2 }, async () => ({ m: 2 }))
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res1 = await request(app).post('/rpc/method-one/1').send({})
+      const res2 = await request(app).post('/rpc/method-two/2').send({})
+
+      expect(res1.status).toBe(200)
+      expect(res2.status).toBe(200)
+      expect(res1.body).toEqual({ m: 1 })
+      expect(res2.body).toEqual({ m: 2 })
+    })
+
+    test('returns the Express application', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const app = builder.build()
+
+      expect(app).toBe(builder.app)
+      expect(typeof app.listen).toBe('function')
+    })
+
+    test('populates docs array after build', () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('MethodOne', { name: 'method-one', version: 1 }, async () => ({}))
+      RPC.Create('MethodTwo', { name: ['nested', 'method'], version: 2 }, async () => ({}))
+
+      expect(builder.docs).toHaveLength(0)
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      expect(builder.docs).toHaveLength(2)
+      expect(builder.docs[0]!.path).toBe('/rpc/method-one/1')
+      expect(builder.docs[1]!.path).toBe('/rpc/nested/method/2')
+    })
+
+    test('passes request body to handler as params', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create(
+        'Echo',
+        { name: 'echo', version: 1, schema: { params: v.object({ data: v.string() }) } },
+        async (ctx, params) => ({ received: params.data })
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await request(app).post('/rpc/echo/1').send({ data: 'test-data' })
+
+      expect(res.body).toEqual({ received: 'test-data' })
+    })
+
+    test('GET requests return 404 (RPC uses POST only)', async () => {
+      const builder = new ExpressRPCAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.Create('Test', { name: 'test', version: 1 }, async () => ({ ok: true }))
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await request(app).get('/rpc/test/1')
+
+      expect(res.status).toBe(404)
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Path Generation Tests (makeRPCHttpRoutePath)
+  // --------------------------------------------------------------------------
+  describe('makeRPCHttpRoutePath', () => {
+    let builder: ExpressRPCAppBuilder
+
+    beforeEach(() => {
+      builder = new ExpressRPCAppBuilder()
+    })
+
+    test("simple string: 'users' → /rpc/users/1", () => {
+      const path = builder.makeRPCHttpRoutePath({ name: 'users', version: 1 })
+      expect(path).toBe('/rpc/users/1')
+    })
+
+    test("array name: ['users', 'get-by-id'] → /rpc/users/get-by-id/1", () => {
+      const path = builder.makeRPCHttpRoutePath({ name: ['users', 'get-by-id'], version: 1 })
+      expect(path).toBe('/rpc/users/get-by-id/1')
+    })
+
+    test("camelCase: 'getUserById' → /rpc/get-user-by-id/1", () => {
+      const path = builder.makeRPCHttpRoutePath({ name: 'getUserById', version: 1 })
+      expect(path).toBe('/rpc/get-user-by-id/1')
+    })
+
+    test("PascalCase: 'GetUserById' → /rpc/get-user-by-id/1", () => {
+      const path = builder.makeRPCHttpRoutePath({ name: 'GetUserById', version: 1 })
+      expect(path).toBe('/rpc/get-user-by-id/1')
+    })
+
+    test('version number included in path', () => {
+      const pathV1 = builder.makeRPCHttpRoutePath({ name: 'test', version: 1 })
+      const pathV2 = builder.makeRPCHttpRoutePath({ name: 'test', version: 2 })
+      const pathV99 = builder.makeRPCHttpRoutePath({ name: 'test', version: 99 })
+
+      expect(pathV1).toBe('/rpc/test/1')
+      expect(pathV2).toBe('/rpc/test/2')
+      expect(pathV99).toBe('/rpc/test/99')
+    })
+
+    test('handles mixed case in array segments', () => {
+      const path = builder.makeRPCHttpRoutePath({
+        name: ['UserModule', 'getActiveUsers'],
+        version: 1,
+      })
+      expect(path).toBe('/rpc/user-module/get-active-users/1')
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Route Documentation Tests (buildRpcHttpRouteDoc)
+  // --------------------------------------------------------------------------
+  describe('buildRpcHttpRouteDoc', () => {
+    let builder: ExpressRPCAppBuilder
+
+    beforeEach(() => {
+      builder = new ExpressRPCAppBuilder()
+    })
+
+    test('generates complete route documentation', () => {
+      const paramsSchema = v.object({ id: v.string() })
+      const returnSchema = v.object({ name: v.string() })
+
+      const RPC = Procedures<{}, RPCConfig>()
+      const { info } = RPC.Create(
+        'GetUser',
+        { name: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } },
+        async () => ({ name: 'test' })
+      )
+
+      const procedure = RPC.getProcedures()[0]!
+      const doc = builder.buildRpcHttpRouteDoc(procedure)
+
+      expect(doc.path).toBe('/rpc/users/1')
+      expect(doc.method).toBe('post')
+      expect(doc.jsonSchema.body).toBeDefined()
+      expect(doc.jsonSchema.response).toBeDefined()
+    })
+
+    test('omits body schema when no params defined', () => {
+      const RPC = Procedures<{}, RPCConfig>()
+      RPC.Create('NoParams', { name: 'no-params', version: 1 }, async () => ({ ok: true }))
+
+      const procedure = RPC.getProcedures()[0]!
+      const doc = builder.buildRpcHttpRouteDoc(procedure)
+
+      expect(doc.jsonSchema.body).toBeUndefined()
+    })
+
+    test('omits response schema when no returnType defined', () => {
+      const RPC = Procedures<{}, RPCConfig>()
+      RPC.Create(
+        'NoReturn',
+        { name: 'no-return', version: 1, schema: { params: v.object({ x: v.number() }) } },
+        async () => ({})
+      )
+
+      const procedure = RPC.getProcedures()[0]!
+      const doc = builder.buildRpcHttpRouteDoc(procedure)
+
+      expect(doc.jsonSchema.body).toBeDefined()
+      expect(doc.jsonSchema.response).toBeUndefined()
+    })
+
+    test("method is always 'post'", () => {
+      const RPC = Procedures<{}, RPCConfig>()
+      RPC.Create('Test1', { name: 't1', version: 1 }, async () => ({}))
+      RPC.Create('Test2', { name: 't2', version: 2 }, async () => ({}))
+
+      const procedures = RPC.getProcedures()
+
+      procedures.forEach((proc) => {
+        const doc = builder.buildRpcHttpRouteDoc(proc)
+        expect(doc.method).toBe('post')
+      })
+    })
+  })
+
+  // --------------------------------------------------------------------------
+  // Integration Test
+  // --------------------------------------------------------------------------
+  describe('integration', () => {
+    test('full workflow with multiple procedure factories and different contexts', async () => {
+      // Define context types
+      type PublicContext = { source: 'public' }
+      type AuthContext = { source: 'auth'; userId: string }
+
+      // Create factories
+      const PublicRPC = Procedures<PublicContext, RPCConfig>()
+      const AuthRPC = Procedures<AuthContext, RPCConfig>()
+
+      // Create public procedures
+      PublicRPC.Create('GetVersion', { name: ['system', 'version'], version: 1 }, async () => ({
+        version: '1.0.0',
+      }))
+
+      PublicRPC.Create('HealthCheck', { name: 'health', version: 1 }, async () => ({
+        status: 'ok',
+      }))
+
+      // Create authenticated procedures
+      AuthRPC.Create(
+        'GetProfile',
+        {
+          name: ['users', 'profile'],
+          version: 1,
+          schema: { returnType: v.object({ userId: v.string(), source: v.string() }) },
+        },
+        async (ctx) => ({ userId: ctx.userId, source: ctx.source })
+      )
+
+      AuthRPC.Create(
+        'UpdateProfile',
+        {
+          name: ['users', 'profile'],
+          version: 2,
+          schema: { params: v.object({ name: v.string() }) },
+        },
+        async (ctx, params) => ({ userId: ctx.userId, name: params.name })
+      )
+
+      // Build app with lifecycle hooks
+      const events: string[] = []
+
+      const builder = new ExpressRPCAppBuilder({
+        onRequestStart: () => events.push('request-start'),
+        onRequestEnd: () => events.push('request-end'),
+        onSuccess: (proc) => events.push(`success:${proc.name}`),
+      })
+
+      builder
+        .register(PublicRPC, () => ({ source: 'public' as const }))
+        .register(AuthRPC, (req) => ({
+          source: 'auth' as const,
+          userId: (req.headers['x-user-id'] as string) || 'anonymous',
+        }))
+
+      const app = builder.build()
+
+      // Test public endpoints
+      const versionRes = await request(app).post('/rpc/system/version/1').send({})
+      expect(versionRes.status).toBe(200)
+      expect(versionRes.body).toEqual({ version: '1.0.0' })
+
+      const healthRes = await request(app).post('/rpc/health/1').send({})
+      expect(healthRes.status).toBe(200)
+      expect(healthRes.body).toEqual({ status: 'ok' })
+
+      // Test authenticated endpoints
+      const profileRes = await request(app)
+        .post('/rpc/users/profile/1')
+        .set('X-User-Id', 'user-123')
+        .send({})
+      expect(profileRes.status).toBe(200)
+      expect(profileRes.body).toEqual({ userId: 'user-123', source: 'auth' })
+
+      const updateRes = await request(app)
+        .post('/rpc/users/profile/2')
+        .set('X-User-Id', 'user-456')
+        .send({ name: 'John Doe' })
+      expect(updateRes.status).toBe(200)
+      expect(updateRes.body).toEqual({ userId: 'user-456', name: 'John Doe' })
+
+      // Verify documentation
+      expect(builder.docs).toHaveLength(4)
+
+      const paths = builder.docs.map((d) => d.path)
+      expect(paths).toContain('/rpc/system/version/1')
+      expect(paths).toContain('/rpc/health/1')
+      expect(paths).toContain('/rpc/users/profile/1')
+      expect(paths).toContain('/rpc/users/profile/2')
+
+      // Verify hooks were called
+      expect(events).toContain('request-start')
+      expect(events).toContain('success:GetVersion')
+      expect(events).toContain('success:HealthCheck')
+      expect(events).toContain('success:GetProfile')
+      expect(events).toContain('success:UpdateProfile')
+      expect(events).toContain('request-end')
+    })
+  })
+})