ts-procedures 9.1.0 → 9.2.0

package/build/implementations/http/error-taxonomy.test.js

@@ -0,0 +1,399 @@
+import { describe, expect, test } from 'vitest';
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, } from '../../errors.js';
+import { defineErrorTaxonomy, resolveErrorResponse, defaultErrorTaxonomy, } from './error-taxonomy.js';
+class UseCaseError extends Error {
+    externalMsg;
+    internalMsg;
+    constructor(externalMsg, internalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.internalMsg = internalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+class AuthError extends Error {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.reason = reason;
+        this.name = 'AuthError';
+        Object.setPrototypeOf(this, AuthError.prototype);
+    }
+}
+const fakeProcedure = { name: 'Test', config: {}, handler: async () => { } };
+describe('defineErrorTaxonomy', () => {
+    test('validates exactly one discriminator per entry', () => {
+        expect(() => defineErrorTaxonomy({
+            Bad: { statusCode: 400 },
+        })).toThrow(/exactly one of/);
+        expect(() => defineErrorTaxonomy({
+            Bad: {
+                class: Error,
+                match: (e) => e instanceof Error,
+                statusCode: 400,
+            },
+        })).toThrow(/exactly one of/);
+    });
+    test('accepts a valid entry', () => {
+        const t = defineErrorTaxonomy({
+            UseCaseError: { class: UseCaseError, statusCode: 422 },
+        });
+        expect(t.UseCaseError.statusCode).toBe(422);
+    });
+});
+describe('resolveErrorResponse', () => {
+    test('class match uses toResponse output', () => {
+        const taxonomy = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new UseCaseError('external', 'internal'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(422);
+        expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'external' });
+    });
+    test('match predicate catches 3rd-party errors', () => {
+        const mongoLike = Object.assign(new Error('dup'), { name: 'MongoServerError', code: 11000 });
+        const taxonomy = defineErrorTaxonomy({
+            MongoDuplicateKey: {
+                match: (e) => e instanceof Error && e.code === 11000,
+                statusCode: 409,
+                toResponse: () => ({ name: 'Conflict' }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: mongoLike,
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(409);
+        expect(resolved?.body).toEqual({ name: 'Conflict' });
+    });
+    test('default toResponse emits { name, message } from entry key', () => {
+        const taxonomy = defineErrorTaxonomy({
+            AuthError: { class: AuthError, statusCode: 401 },
+        });
+        const resolved = resolveErrorResponse({
+            err: new AuthError('unauthenticated'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.body).toEqual({ name: 'AuthError', message: 'unauthenticated' });
+    });
+    test('first matching entry wins — subclass declared before base', () => {
+        const taxonomy = defineErrorTaxonomy({
+            ProcedureValidationError: {
+                class: ProcedureValidationError,
+                statusCode: 400,
+                toResponse: () => ({ kind: 'validation' }),
+            },
+            ProcedureError: {
+                class: ProcedureError,
+                statusCode: 500,
+                toResponse: () => ({ kind: 'base' }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            includeDefaults: false,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(400);
+        expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' });
+    });
+    test('topological sort fixes a subclass that was declared after its base', () => {
+        // Under first-match-wins without sorting, the base would catch the
+        // subclass. defineErrorTaxonomy reorders to keep the subclass entry first.
+        const taxonomy = defineErrorTaxonomy({
+            ProcedureError: {
+                class: ProcedureError,
+                statusCode: 500,
+                toResponse: () => ({ kind: 'base' }),
+            },
+            ProcedureValidationError: {
+                class: ProcedureValidationError,
+                statusCode: 400,
+                toResponse: () => ({ kind: 'validation' }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            includeDefaults: false,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(400);
+        expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' });
+    });
+    test('falls through to unknownError when nothing matches', () => {
+        const resolved = resolveErrorResponse({
+            err: new Error('boom'),
+            userTaxonomy: defineErrorTaxonomy({
+                AuthError: { class: AuthError, statusCode: 401 },
+            }),
+            includeDefaults: false,
+            unknownError: {
+                statusCode: 500,
+                toResponse: () => ({ name: 'InternalServerError' }),
+            },
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(500);
+        expect(resolved?.body).toEqual({ name: 'InternalServerError' });
+    });
+    test('returns null when nothing matches and no unknownError', () => {
+        const resolved = resolveErrorResponse({
+            err: new Error('boom'),
+            userTaxonomy: defineErrorTaxonomy({
+                AuthError: { class: AuthError, statusCode: 401 },
+            }),
+            includeDefaults: false,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved).toBeNull();
+    });
+    test('default taxonomy catches ProcedureValidationError with status 400', () => {
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(400);
+        expect((resolved?.body).name).toBe('ProcedureValidationError');
+    });
+    test('default taxonomy catches ProcedureYieldValidationError with status 500', () => {
+        const resolved = resolveErrorResponse({
+            err: new ProcedureYieldValidationError('Test', 'bad yield', []),
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(500);
+        expect((resolved?.body).name).toBe('ProcedureYieldValidationError');
+    });
+    test('includeDefaults: false disables the default taxonomy', () => {
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            includeDefaults: false,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved).toBeNull();
+    });
+    test('user entry overrides default for the same class', () => {
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            userTaxonomy: defineErrorTaxonomy({
+                ProcedureValidationError: {
+                    class: ProcedureValidationError,
+                    statusCode: 418,
+                    toResponse: () => ({ overridden: true }),
+                },
+            }),
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(418);
+        expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', overridden: true });
+    });
+    test('onCatch is awaited via runOnCatch', async () => {
+        const calls = [];
+        const taxonomy = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                onCatch: async (err) => {
+                    await new Promise((r) => setTimeout(r, 5));
+                    calls.push(err.internalMsg);
+                },
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new UseCaseError('ext', 'internal-log'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(calls).toEqual([]);
+        await resolved.runOnCatch();
+        expect(calls).toEqual(['internal-log']);
+    });
+    test('unknownError onCatch is awaited', async () => {
+        const calls = [];
+        const resolved = resolveErrorResponse({
+            err: new Error('boom'),
+            includeDefaults: false,
+            unknownError: {
+                toResponse: () => ({}),
+                onCatch: async (err) => {
+                    await Promise.resolve();
+                    calls.push(err);
+                },
+            },
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        await resolved.runOnCatch();
+        expect(calls).toHaveLength(1);
+        expect(calls[0].message).toBe('boom');
+    });
+    test('onCatch receives procedure, key and raw', async () => {
+        let received;
+        const taxonomy = defineErrorTaxonomy({
+            AuthError: {
+                class: AuthError,
+                statusCode: 401,
+                onCatch: (_err, ctx) => {
+                    received = ctx;
+                },
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new AuthError('forbidden'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: { marker: 'hono-context' },
+        });
+        await resolved.runOnCatch();
+        expect(received.procedure).toBe(fakeProcedure);
+        expect(received.key).toBe('AuthError');
+        expect(received.raw).toEqual({ marker: 'hono-context' });
+    });
+    test('defaultErrorTaxonomy exposes all four framework error mappings', () => {
+        expect(defaultErrorTaxonomy.ProcedureValidationError.statusCode).toBe(400);
+        expect(defaultErrorTaxonomy.ProcedureYieldValidationError.statusCode).toBe(500);
+        expect(defaultErrorTaxonomy.ProcedureError.statusCode).toBe(500);
+    });
+    test('user taxonomy matches cause inside a ProcedureError wrapper', () => {
+        // Simulates what the core does when a non-ProcedureError is thrown: wraps
+        // into ProcedureError with `cause` preserved.
+        const original = new UseCaseError('public', 'private');
+        const wrapped = new ProcedureError('Test', 'wrapped');
+        wrapped.cause = original;
+        const taxonomy = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: wrapped,
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(422);
+        expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'public' });
+    });
+    test('wrapped ProcedureError falls through default taxonomy to unknownError', () => {
+        const original = new TypeError('db-broke');
+        const wrapped = new ProcedureError('Test', 'wrapped');
+        wrapped.cause = original;
+        const resolved = resolveErrorResponse({
+            err: wrapped,
+            unknownError: {
+                statusCode: 500,
+                toResponse: (err) => ({ name: 'InternalServerError', type: err.constructor.name }),
+            },
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(500);
+        expect(resolved?.body).toEqual({ name: 'InternalServerError', type: 'TypeError' });
+    });
+    test('direct ProcedureError (no cause) still caught by default entry', () => {
+        const direct = new ProcedureError('Test', 'from ctx.error');
+        const resolved = resolveErrorResponse({
+            err: direct,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(500);
+        expect((resolved?.body).name).toBe('ProcedureError');
+    });
+    test('auto-injects name when toResponse omits it', () => {
+        const taxonomy = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                // Returns a body without `name` — resolver should add one.
+                toResponse: (err) => ({ message: err.externalMsg, detail: err.internalMsg }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new UseCaseError('ext', 'int'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'ext', detail: 'int' });
+    });
+    test('preserves explicit name in toResponse output', () => {
+        const taxonomy = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                toResponse: () => ({ name: 'CustomAlias', reason: 'x' }),
+            },
+        });
+        const resolved = resolveErrorResponse({
+            err: new UseCaseError('ext', 'int'),
+            userTaxonomy: taxonomy,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect((resolved?.body).name).toBe('CustomAlias');
+    });
+    test('defineErrorTaxonomy topologically sorts class entries (subclass before base)', () => {
+        // Declared base-before-subclass on purpose — sort must swap them.
+        const taxonomy = defineErrorTaxonomy({
+            ProcedureError: {
+                class: ProcedureError,
+                statusCode: 500,
+                toResponse: () => ({ kind: 'base' }),
+            },
+            ProcedureValidationError: {
+                class: ProcedureValidationError,
+                statusCode: 400,
+                toResponse: () => ({ kind: 'validation' }),
+            },
+        });
+        const keys = Object.keys(taxonomy);
+        expect(keys).toEqual(['ProcedureValidationError', 'ProcedureError']);
+        const resolved = resolveErrorResponse({
+            err: new ProcedureValidationError('Test', 'bad', []),
+            userTaxonomy: taxonomy,
+            includeDefaults: false,
+            procedure: fakeProcedure,
+            raw: {},
+        });
+        expect(resolved?.statusCode).toBe(400);
+    });
+    test('topological sort preserves declared order for unrelated classes', () => {
+        class A extends Error {
+        }
+        class B extends Error {
+        }
+        const taxonomy = defineErrorTaxonomy({
+            B: { class: B, statusCode: 400 },
+            A: { class: A, statusCode: 400 },
+        });
+        expect(Object.keys(taxonomy)).toEqual(['B', 'A']);
+    });
+});
+//# sourceMappingURL=error-taxonomy.test.js.map

package/build/implementations/http/error-taxonomy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-taxonomy.test.js","sourceRoot":"","sources":["../../../src/implementations/http/error-taxonomy.test.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/express-rpc/error-taxonomy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/implementations/http/express-rpc/error-taxonomy.test.js

@@ -0,0 +1,83 @@
+import { describe, expect, test, vi } from 'vitest';
+import request from 'supertest';
+import { Type } from 'typebox';
+import { Procedures } from '../../../index.js';
+import { ExpressRPCAppBuilder, defineErrorTaxonomy } from './index.js';
+class UseCaseError extends Error {
+    externalMsg;
+    internalMsg;
+    constructor(externalMsg, internalMsg) {
+        super(externalMsg);
+        this.externalMsg = externalMsg;
+        this.internalMsg = internalMsg;
+        this.name = 'UseCaseError';
+        Object.setPrototypeOf(this, UseCaseError.prototype);
+    }
+}
+describe('ExpressRPCAppBuilder — error taxonomy', () => {
+    test('taxonomy catches user error thrown from RPC handler', async () => {
+        const errors = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
+            },
+        });
+        const RPC = Procedures();
+        RPC.Create('Boom', { scope: 'test', version: 1, schema: { params: Type.Object({}) } }, async () => {
+            throw new UseCaseError('ext', 'int');
+        });
+        const app = new ExpressRPCAppBuilder({ errors }).register(RPC, () => ({})).build();
+        const res = await request(app).post('/test/boom/1').send({});
+        expect(res.status).toBe(422);
+        expect(res.body).toEqual({ name: 'UseCaseError', message: 'ext' });
+    });
+    test('unknownError catches unmapped errors', async () => {
+        const RPC = Procedures();
+        RPC.Create('Boom', { scope: 'test', version: 1, schema: { params: Type.Object({}) } }, async () => {
+            throw new TypeError('db down');
+        });
+        const app = new ExpressRPCAppBuilder({
+            unknownError: { statusCode: 503, toResponse: () => ({ name: 'ServiceUnavailable' }) },
+        })
+            .register(RPC, () => ({}))
+            .build();
+        const res = await request(app).post('/test/boom/1').send({});
+        expect(res.status).toBe(503);
+        expect(res.body).toEqual({ name: 'ServiceUnavailable' });
+    });
+    test('onCatch receives { req, res } as raw context', async () => {
+        let rawSeen;
+        const errors = defineErrorTaxonomy({
+            UseCaseError: {
+                class: UseCaseError,
+                statusCode: 422,
+                onCatch: (_err, ctx) => {
+                    rawSeen = ctx.raw;
+                },
+            },
+        });
+        const RPC = Procedures();
+        RPC.Create('Boom', { scope: 'test', version: 1, schema: { params: Type.Object({}) } }, async () => {
+            throw new UseCaseError('ext', 'int');
+        });
+        const app = new ExpressRPCAppBuilder({ errors }).register(RPC, () => ({})).build();
+        await request(app).post('/test/boom/1').send({});
+        expect(rawSeen.req).toBeDefined();
+        expect(rawSeen.res).toBeDefined();
+    });
+    test('onError callback handles errors not matched by the taxonomy', async () => {
+        const onError = vi.fn((_p, _req, res) => {
+            res.status(418).json({ legacy: true });
+        });
+        const RPC = Procedures();
+        RPC.Create('Boom', { scope: 'test', version: 1, schema: { params: Type.Object({}) } }, async () => {
+            throw new TypeError('legacy');
+        });
+        const app = new ExpressRPCAppBuilder({ onError }).register(RPC, () => ({})).build();
+        const res = await request(app).post('/test/boom/1').send({});
+        expect(res.status).toBe(418);
+        expect(onError).toHaveBeenCalledOnce();
+    });
+});
+//# sourceMappingURL=error-taxonomy.test.js.map

package/build/implementations/http/express-rpc/error-taxonomy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-taxonomy.test.js","sourceRoot":"","sources":["../../../../src/implementations/http/express-rpc/error-taxonomy.test.ts"],"names":[],"mappings":"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"}

package/build/implementations/http/express-rpc/index.d.ts

@@ -0,0 +1,125 @@
+import express from 'express';
+import { TProcedureRegistration } from '../../../index.js';
+import { ExtractConfig, ExtractContext, ProceduresFactory, RPCConfig, RPCHttpRouteDoc } from '../../types.js';
+import { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig, defineErrorTaxonomy } from '../error-taxonomy.js';
+export type { RPCConfig, RPCHttpRouteDoc };
+export { defineErrorTaxonomy };
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig };
+export type ExpressRPCAppBuilderConfig = {
+    /**
+     * An existing Express application instance to use.
+     * When provided, ensure to set up necessary middleware (e.g., json/body parser) beforehand.
+     * If not provided, a new instance will be created.
+     */
+    app?: express.Express;
+    /** Optional path prefix for all RPC routes. */
+    pathPrefix?: string;
+    onRequestStart?: (req: express.Request) => void;
+    onRequestEnd?: (req: express.Request, res: express.Response) => void;
+    onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void;
+    /**
+     * Declarative error-to-response mapping (one of the two peer error modes).
+     * See hono-api for the full taxonomy contract. The `raw` field passed to
+     * taxonomy callbacks is `{ req, res }`.
+     */
+    errors?: ErrorTaxonomy;
+    /** Fallback serializer for errors not matched by the taxonomy. */
+    unknownError?: UnknownErrorConfig;
+    /**
+     * Imperative error callback — the other peer error mode. Receives every
+     * error directly and writes the response via `res`. Use this when you want
+     * full control, or alongside `errors` for the tail of errors the taxonomy
+     * doesn't cover.
+     */
+    onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void;
+    /**
+     * Cross-cutting observer — fires for every caught error, BEFORE dispatch.
+     * Awaited. Cannot write to `res` (observer only — check `res.headersSent`
+     * if you must touch it). Thrown errors inside the observer are swallowed
+     * and logged.
+     */
+    onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>;
+};
+/**
+ * Context passed to the `onRequestError` observer. `raw` is `{ req, res }`
+ * for the in-flight request.
+ */
+export type OnRequestErrorContext = {
+    err: unknown;
+    procedure: TProcedureRegistration;
+    raw: {
+        req: express.Request;
+        res: express.Response;
+    };
+};
+/**
+ * Builder class for creating an Express application with RPC routes.
+ *
+ * Usage:
+ *   const PublicRPC = Procedures<PublicRPCContext, RPCConfig>()
+ *   const ProtectedRPC = Procedures<ProtectedRPCContext, RPCConfig>()
+ *
+ *   const rpcApp = new ExpressRPCAppBuilder()
+ *     .register(PublicRPC, (req): Promise<PublicRPCContext> => { /* context resolution logic * / })
+ *     .register(ProtectedRPC, (req): Promise<ProtectedRPCContext> => { /* context resolution logic * / })
+ *     .build();
+ *
+ *   const app = rpcApp.app; // Express application
+ *   const docs = rpcApp.docs; // RPC route documentation
+ */
+export declare class ExpressRPCAppBuilder {
+    readonly config?: ExpressRPCAppBuilderConfig | undefined;
+    /**
+     * Constructor for ExpressRPCAppBuilder.
+     *
+     * @param config
+     */
+    constructor(config?: ExpressRPCAppBuilderConfig | undefined);
+    /**
+     * Generates the RPC route path based on the RPC configuration.
+     * `RPCConfig.scope` can be a string or an array of strings to form nested paths.
+     *
+     * Example
+     *  name:  'GetUser'
+     *  scope: ['users', 'profile']
+     *  version: 1
+     *  path: /users/profile/get-user/1
+     * @param config
+     */
+    static makeRPCHttpRoutePath({ name, config, prefix, }: {
+        name: string;
+        prefix?: string;
+        config: RPCConfig;
+    }): string;
+    /**
+     * Instance method wrapper for makeRPCHttpRoutePath that uses the builder's pathPrefix.
+     * @param config - The RPC configuration
+     */
+    makeRPCHttpRoutePath(name: string, config: RPCConfig): string;
+    private factories;
+    private _app;
+    private _docs;
+    get app(): express.Express;
+    get docs(): RPCHttpRouteDoc[];
+    /**
+     * Registers a procedure factory with its context.
+     * @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>>), extendProcedureDoc?: (params: {
+        base: RPCHttpRouteDoc;
+        procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>;
+    }) => Record<string, any>): this;
+    /**
+     * Builds and returns the Express application with registered RPC routes.
+     * @return express.Application
+     */
+    build(): express.Application;
+    /**
+     * Generates the RPC HTTP route for the given procedure.
+     * @param procedure
+     */
+    private buildRpcHttpRouteDoc;
+}