ts-procedures 5.9.1 → 5.10.2

package/build/src/implementations/http/express-rpc/index.test.js

@@ -0,0 +1,684 @@
+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';
+/**
+ * ExpressRPCAppBuilder Test Suite
+ *
+ * Tests the RPC-style Express integration for ts-procedures.
+ * This builder creates POST routes at `/{name}/{version}` paths (with optional pathPrefix).
+ */
+describe('ExpressRPCAppBuilder', () => {
+    // --------------------------------------------------------------------------
+    // Constructor Tests
+    // --------------------------------------------------------------------------
+    describe('constructor', () => {
+        test('creates default Express app with json middleware', async () => {
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('Echo', { scope: '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('/echo/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();
+            RPC.Create('Echo', { scope: '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('/echo/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([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // pathPrefix Option Tests
+    // --------------------------------------------------------------------------
+    describe('pathPrefix option', () => {
+        test('uses custom pathPrefix for all routes', async () => {
+            const builder = new ExpressRPCAppBuilder({ pathPrefix: '/api/v1' });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/api/v1/test/test/1').send({});
+            expect(res.status).toBe(200);
+            expect(res.body).toEqual({ ok: true });
+        });
+        test('pathPrefix without leading slash gets normalized', async () => {
+            const builder = new ExpressRPCAppBuilder({ pathPrefix: 'custom' });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/custom/test/test/1').send({});
+            expect(res.status).toBe(200);
+        });
+        test('no prefix when pathPrefix not specified', async () => {
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/test/test/1').send({});
+            expect(res.status).toBe(200);
+        });
+        test('pathPrefix appears in generated docs', () => {
+            const builder = new ExpressRPCAppBuilder({ pathPrefix: '/api' });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({}));
+            builder.register(RPC, () => ({}));
+            builder.build();
+            expect(builder.docs[0].path).toBe('/api/test/test/1');
+        });
+        test('pathPrefix /rpc restores original behavior', async () => {
+            const builder = new ExpressRPCAppBuilder({ pathPrefix: '/rpc' });
+            const RPC = Procedures();
+            RPC.Create('Users', { scope: 'users', version: 1 }, async () => ({ users: [] }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/rpc/users/users/1').send({});
+            expect(res.status).toBe(200);
+            expect(builder.docs[0].path).toBe('/rpc/users/users/1');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // 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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await request(app).post('/test/test/1').send({});
+            expect(onRequestStart).toHaveBeenCalledTimes(1);
+            expect(onRequestStart.mock.calls[0][0]).toHaveProperty('method', 'POST');
+            expect(onRequestStart.mock.calls[0][0]).toHaveProperty('path', '/test/test/1');
+        });
+        test('onRequestEnd is called after response finishes', async () => {
+            const onRequestEnd = vi.fn();
+            const builder = new ExpressRPCAppBuilder({ onRequestEnd });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await request(app).post('/test/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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await request(app).post('/test/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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
+                throw new Error('Handler error');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await request(app).post('/test/test/1').send({});
+            expect(onSuccess).not.toHaveBeenCalled();
+        });
+        test('hooks execute in correct order: start → handler → success → end', async () => {
+            const order = [];
+            const builder = new ExpressRPCAppBuilder({
+                onRequestStart: () => order.push('start'),
+                onRequestEnd: () => order.push('end'),
+                onSuccess: () => order.push('success'),
+            });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
+                order.push('handler');
+                return { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await request(app).post('/test/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({ onError: errorHandler });
+            const RPC = Procedures();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
+                throw new Error('Test error');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/test/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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
+                throw new Error('Something went wrong');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/test/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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => {
+                // Simulate unhandled exception
+                const obj = null;
+                return obj.property; // This will throw
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).post('/test/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();
+            const RPC2 = Procedures();
+            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();
+            const PrivateRPC = Procedures();
+            PublicRPC.Create('PublicMethod', { scope: 'public', version: 1 }, async (ctx) => ({
+                isPublic: ctx.public,
+            }));
+            PrivateRPC.Create('PrivateMethod', { scope: 'private', version: 1 }, async (ctx) => ({
+                isPrivate: ctx.private,
+            }));
+            builder
+                .register(PublicRPC, () => ({ public: true }))
+                .register(PrivateRPC, () => ({ private: true }));
+            const app = builder.build();
+            const publicRes = await request(app).post('/public/public-method/1').send({});
+            const privateRes = await request(app).post('/private/private-method/1').send({});
+            expect(publicRes.body).toEqual({ isPublic: true });
+            expect(privateRes.body).toEqual({ isPrivate: true });
+        });
+        test('context can be a static object', async () => {
+            const factoryContext = { requestId: 'req-123' };
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
+                id: ctx.requestId,
+            }));
+            builder.register(RPC, factoryContext);
+            const app = builder.build();
+            const res = await request(app).post('/get-request-id/get-request-id/1').send({});
+            expect(res.body).toEqual({ id: 'req-123' });
+        });
+        test('factoryContext can be async function', async () => {
+            const factoryContext = vi.fn(async () => {
+                return { requestId: 'req-456' };
+            });
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('GetRequestId', { scope: 'get-request-id', version: 1 }, async (ctx) => ({
+                id: ctx.requestId,
+            }));
+            builder.register(RPC, factoryContext);
+            const app = builder.build();
+            await request(app).post('/get-request-id/get-request-id/1').send({});
+            expect(factoryContext).toHaveBeenCalledTimes(1);
+        });
+        test('factoryContext function receives Express request object', async () => {
+            const factoryContext = vi.fn((req) => ({
+                authHeader: req.headers.authorization,
+            }));
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('GetAuth', { scope: 'get-auth', version: 1 }, async (ctx) => ({
+                auth: ctx.authHeader,
+            }));
+            builder.register(RPC, factoryContext);
+            const app = builder.build();
+            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');
+            expect(factoryContext.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();
+            RPC.Create('MethodOne', { scope: 'method-one', version: 1 }, async () => ({ m: 1 }));
+            RPC.Create('MethodTwo', { scope: 'method-two', version: 2 }, async () => ({ m: 2 }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res1 = await request(app).post('/method-one/method-one/1').send({});
+            const res2 = await request(app).post('/method-two/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();
+            RPC.Create('MethodOne', { scope: 'method-one', version: 1 }, async () => ({}));
+            RPC.Create('MethodTwo', { scope: ['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('/method-one/method-one/1');
+            expect(builder.docs[1].path).toBe('/nested/method/method-two/2');
+        });
+        test('passes request body to handler as params', async () => {
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            RPC.Create('Echo', { scope: '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('/echo/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();
+            RPC.Create('Test', { scope: 'test', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await request(app).get('/test/test/1');
+            expect(res.status).toBe(404);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Path Generation Tests (makeRPCHttpRoutePath)
+    // --------------------------------------------------------------------------
+    describe('makeRPCHttpRoutePath', () => {
+        let builder;
+        beforeEach(() => {
+            builder = new ExpressRPCAppBuilder();
+        });
+        test("simple scope with procedure name: 'users' + 'GetUser' → /users/get-user/1", () => {
+            const path = builder.makeRPCHttpRoutePath('GetUser', { scope: 'users', version: 1 });
+            expect(path).toBe('/users/get-user/1');
+        });
+        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,
+            });
+            expect(path).toBe('/users/profile/get-by-id/1');
+        });
+        test("camelCase procedure name: 'users' + 'getProfile' → /users/get-profile/1", () => {
+            const path = builder.makeRPCHttpRoutePath('getProfile', { scope: 'users', version: 1 });
+            expect(path).toBe('/users/get-profile/1');
+        });
+        test("PascalCase procedure name: 'users' + 'UpdateProfile' → /users/update-profile/1", () => {
+            const path = builder.makeRPCHttpRoutePath('UpdateProfile', { scope: 'users', version: 1 });
+            expect(path).toBe('/users/update-profile/1');
+        });
+        test('version number included in path', () => {
+            const pathV1 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 1 });
+            const pathV2 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 2 });
+            const pathV99 = builder.makeRPCHttpRoutePath('Test', { scope: 'test', version: 99 });
+            expect(pathV1).toBe('/test/test/1');
+            expect(pathV2).toBe('/test/test/2');
+            expect(pathV99).toBe('/test/test/99');
+        });
+        test('handles mixed case in array segments', () => {
+            const path = builder.makeRPCHttpRoutePath('ListUsers', {
+                scope: ['UserModule', 'getActiveUsers'],
+                version: 1,
+            });
+            expect(path).toBe('/user-module/get-active-users/list-users/1');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Route Documentation Tests (buildRpcHttpRouteDoc)
+    // --------------------------------------------------------------------------
+    describe('buildRpcHttpRouteDoc', () => {
+        let builder;
+        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();
+            RPC.Create('GetUser', { scope: 'users', version: 1, schema: { params: paramsSchema, returnType: returnSchema } }, async () => ({ name: 'test' }));
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc.path).toBe('/users/get-user/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();
+            RPC.Create('NoParams', { scope: 'no-params', version: 1 }, async () => ({ ok: true }));
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc.jsonSchema.body).toBeUndefined();
+        });
+        test('omits response schema when no returnType defined', () => {
+            const RPC = Procedures();
+            RPC.Create('NoReturn', { scope: 'no-return', version: 1, schema: { params: v.object({ x: v.number() }) } }, async () => ({}));
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc.jsonSchema.body).toBeDefined();
+            expect(doc.jsonSchema.response).toBeUndefined();
+        });
+        test("method is always 'post'", () => {
+            const RPC = Procedures();
+            RPC.Create('Test1', { scope: 't1', version: 1 }, async () => ({}));
+            RPC.Create('Test2', { scope: 't2', version: 2 }, async () => ({}));
+            builder.register(RPC, () => ({}));
+            builder.build();
+            builder.docs.forEach((doc) => {
+                expect(doc.method).toBe('post');
+            });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // extendProcedureDoc Tests
+    // --------------------------------------------------------------------------
+    describe('extendProcedureDoc', () => {
+        test('adds custom properties to generated documentation', () => {
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            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();
+            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];
+            // 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();
+            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();
+            const AdminRPC = Procedures();
+            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();
+            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) => 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();
+            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(['kind', 'name', 'version', 'scope', 'path', 'method', 'jsonSchema']);
+        });
+        test('extendProcedureDoc can access procedure config for conditional logic', () => {
+            const builder = new ExpressRPCAppBuilder();
+            const RPC = Procedures();
+            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();
+            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];
+            expect(doc).toHaveProperty('requestBody');
+            expect(doc.requestBody).toHaveProperty('content');
+            expect(doc).toHaveProperty('responses');
+            expect(doc.responses).toHaveProperty('200');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Integration Test
+    // --------------------------------------------------------------------------
+    describe('integration', () => {
+        test('full workflow with multiple procedure factories and different contexts', async () => {
+            // Create factories
+            const PublicRPC = Procedures();
+            const AuthRPC = Procedures();
+            // Create public procedures
+            PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
+                version: '1.0.0',
+            }));
+            PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
+                status: 'ok',
+            }));
+            // Create authenticated procedures
+            AuthRPC.Create('GetProfile', {
+                scope: ['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', {
+                scope: ['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 = [];
+            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' }))
+                .register(AuthRPC, (req) => ({
+                source: 'auth',
+                userId: req.headers['x-user-id'] || 'anonymous',
+            }));
+            const app = builder.build();
+            // Test public endpoints
+            const versionRes = await request(app).post('/system/version/get-version/1').send({});
+            expect(versionRes.status).toBe(200);
+            expect(versionRes.body).toEqual({ version: '1.0.0' });
+            const healthRes = await request(app).post('/health/health-check/1').send({});
+            expect(healthRes.status).toBe(200);
+            expect(healthRes.body).toEqual({ status: 'ok' });
+            // Test authenticated endpoints
+            const profileRes = await request(app)
+                .post('/users/profile/get-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('/users/profile/update-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('/system/version/get-version/1');
+            expect(paths).toContain('/health/health-check/1');
+            expect(paths).toContain('/users/profile/get-profile/1');
+            expect(paths).toContain('/users/profile/update-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');
+        });
+    });
+});
+//# sourceMappingURL=index.test.js.map