ts-procedures 10.1.1 → 10.2.0

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

@@ -0,0 +1,216 @@
+import express from 'express';
+import { kebabCase } from 'es-toolkit/string';
+import { defineErrorTaxonomy, resolveErrorResponse, } from '../error-taxonomy.js';
+import { castArray } from 'es-toolkit/compat';
+export { defineErrorTaxonomy };
+/**
+ * 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 class ExpressRPCAppBuilder {
+    config;
+    /**
+     * Constructor for ExpressRPCAppBuilder.
+     *
+     * @param config
+     */
+    constructor(config) {
+        this.config = config;
+        if (config?.app) {
+            this._app = config.app;
+        }
+        else {
+            // Default middleware if no app is provided
+            this._app.use(express.json());
+        }
+        if (config?.onRequestStart) {
+            this._app.use((req, res, next) => {
+                config.onRequestStart(req);
+                next();
+            });
+        }
+        if (config?.onRequestEnd) {
+            this._app.use((req, res, next) => {
+                res.on('finish', () => {
+                    config.onRequestEnd(req, res);
+                });
+                next();
+            });
+        }
+    }
+    /**
+     * 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, }) {
+        const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : '';
+        return `${normalizedPrefix}/${castArray(config.scope).map(kebabCase).join('/')}/${kebabCase(name)}/${String(config.version).trim()}`;
+    }
+    /**
+     * Instance method wrapper for makeRPCHttpRoutePath that uses the builder's pathPrefix.
+     * @param config - The RPC configuration
+     */
+    makeRPCHttpRoutePath(name, config) {
+        return ExpressRPCAppBuilder.makeRPCHttpRoutePath({
+            name,
+            config,
+            prefix: this.config?.pathPrefix,
+        });
+    }
+    factories = [];
+    _app = express();
+    _docs = [];
+    get app() {
+        return this._app;
+    }
+    get docs() {
+        return this._docs;
+    }
+    /**
+     * 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(factory, factoryContext, extendProcedureDoc) {
+        this.factories.push({ factory, factoryContext, extendProcedureDoc });
+        return this;
+    }
+    /**
+     * Builds and returns the Express application with registered RPC routes.
+     * @return express.Application
+     */
+    build() {
+        this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
+            factory.getProcedures().map((procedure) => {
+                const route = this.buildRpcHttpRouteDoc(procedure, extendProcedureDoc);
+                this._docs.push(route);
+                this._app[route.method](route.path, async (req, res) => {
+                    try {
+                        const context = typeof factoryContext === 'function'
+                            ? await factoryContext(req)
+                            : factoryContext;
+                        let ac;
+                        const ctxWithSignal = Object.defineProperty({ ...context }, 'signal', {
+                            get() {
+                                if (!ac) {
+                                    ac = new AbortController();
+                                    req.on('close', () => { if (!res.writableFinished)
+                                        ac.abort(); });
+                                }
+                                return ac.signal;
+                            },
+                            enumerable: true,
+                        });
+                        res.json(await procedure.handler(ctxWithSignal, req.body));
+                        if (this.config?.onSuccess) {
+                            this.config.onSuccess(procedure, req, res);
+                        }
+                        // if status not set, set to 200
+                        if (!res.status) {
+                            res.status(200);
+                        }
+                    }
+                    catch (error) {
+                        if (this.config?.onRequestError) {
+                            try {
+                                await this.config.onRequestError({ err: error, procedure, raw: { req, res } });
+                            }
+                            catch (observerErr) {
+                                console.error('[ts-procedures express-rpc] onRequestError threw — swallowed:', observerErr);
+                            }
+                        }
+                        if (this.config?.errors || this.config?.unknownError) {
+                            const resolved = resolveErrorResponse({
+                                err: error,
+                                userTaxonomy: this.config.errors,
+                                unknownError: this.config.unknownError,
+                                procedure,
+                                raw: { req, res },
+                            });
+                            if (resolved) {
+                                await resolved.runOnCatch();
+                                if (!res.headersSent) {
+                                    res.status(resolved.statusCode).json(resolved.body);
+                                }
+                                return;
+                            }
+                        }
+                        if (this.config?.onError) {
+                            this.config.onError(procedure, req, res, error);
+                            return;
+                        }
+                        // Hard default — `res.status` is always truthy (it's a method),
+                        // so the previous `if (!res.status)` guard never ran. Set status
+                        // and body together unconditionally, respecting an already-sent
+                        // response.
+                        if (!res.headersSent) {
+                            res.status(500).json({ error: error.message });
+                        }
+                    }
+                });
+            });
+        });
+        return this._app;
+    }
+    /**
+     * Generates the RPC HTTP route for the given procedure.
+     * @param procedure
+     */
+    buildRpcHttpRouteDoc(procedure, extendProcedureDoc) {
+        const { config } = procedure;
+        const path = ExpressRPCAppBuilder.makeRPCHttpRoutePath({
+            name: procedure.name,
+            config,
+            prefix: this.config?.pathPrefix,
+        });
+        const method = 'post'; // RPCs use POST method
+        const jsonSchema = {};
+        if (config.schema?.params) {
+            jsonSchema.body = config.schema.params;
+        }
+        if (config.schema?.returnType) {
+            jsonSchema.response = config.schema.returnType;
+        }
+        const base = {
+            kind: 'rpc',
+            name: procedure.name,
+            version: config.version,
+            scope: config.scope,
+            path,
+            method,
+            jsonSchema,
+        };
+        if (config.errors && config.errors.length > 0) {
+            base.errors = [...config.errors];
+        }
+        let extendedDoc = {};
+        if (extendProcedureDoc) {
+            extendedDoc = extendProcedureDoc({ base, procedure });
+        }
+        return {
+            ...extendedDoc,
+            ...base,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/build/implementations/http/express-rpc/index.js.map

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

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

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