@themainstack/communication 1.0.0

package/src/grpc/server-factory.ts

@@ -0,0 +1,263 @@
+import * as grpc from '@grpc/grpc-js';
+import * as protoLoader from '@grpc/proto-loader';
+import * as path from 'path';
+import * as fs from 'fs';
+import { generateProtoFromMethods, MethodDefinition } from '../proto-generator';
+
+/**
+ * Options for creating a gRPC server
+ */
+export interface GrpcServerOptions {
+    /** The package name (e.g., 'fee.v1') */
+    packageName: string;
+    /** The service name (e.g., 'FeeService') */
+    serviceName: string;
+    /** Port to listen on (default: 50051) */
+    port?: number;
+    /** Host to bind to (default: '0.0.0.0') */
+    host?: string;
+    /** Path to existing proto file (if not provided, will auto-generate) */
+    protoPath?: string;
+    /** Directory to save auto-generated proto (default: './grpc') */
+    protoOutputDir?: string;
+}
+
+/**
+ * Method handler definition for the server
+ */
+export interface ServerMethodHandler<TReq = any, TRes = any> {
+    /** Method name (e.g., 'CalculateWithdrawalFee') */
+    name: string;
+    /** The actual handler function */
+    handler: (request: TReq) => Promise<TRes> | TRes;
+    /** Sample request for proto generation */
+    requestSample: () => TReq;
+    /** Sample response for proto generation */
+    responseSample: () => TRes;
+}
+
+/**
+ * GrpcServerFactory - Create and run gRPC servers easily
+ * 
+ * Usage:
+ * ```typescript
+ * const server = await GrpcServerFactory.createServer({
+ *   packageName: 'fee.v1',
+ *   serviceName: 'FeeService',
+ *   port: 50053,
+ * }, [
+ *   {
+ *     name: 'CalculateWithdrawalFee',
+ *     handler: async (req) => calculateFee(req),
+ *     requestSample: () => ({ merchantId: '', amount: 0 }),
+ *     responseSample: () => ({ dollarAmount: 0, fees: [] }),
+ *   }
+ * ]);
+ * 
+ * await server.start();
+ * ```
+ */
+export class GrpcServerFactory {
+    private server: grpc.Server;
+    private options: Required<GrpcServerOptions>;
+    private isRunning: boolean = false;
+
+    private constructor(
+        server: grpc.Server,
+        options: Required<GrpcServerOptions>
+    ) {
+        this.server = server;
+        this.options = options;
+    }
+
+    /**
+     * Create a new gRPC server with the given handlers
+     */
+    static async createServer(
+        options: GrpcServerOptions,
+        handlers: ServerMethodHandler[]
+    ): Promise<GrpcServerFactory> {
+        const fullOptions: Required<GrpcServerOptions> = {
+            port: 50051,
+            host: '0.0.0.0',
+            protoOutputDir: './grpc',
+            protoPath: '',
+            ...options,
+        };
+
+        // Step 1: Generate or load proto file
+        let protoPath = fullOptions.protoPath;
+
+        if (!protoPath) {
+            // Auto-generate proto from handlers
+            const methodDefinitions: MethodDefinition<any, any>[] = handlers.map(h => ({
+                name: h.name,
+                requestSample: h.requestSample,
+                responseSample: h.responseSample,
+            }));
+
+            const protoContent = generateProtoFromMethods(methodDefinitions, {
+                packageName: fullOptions.packageName,
+                serviceName: fullOptions.serviceName,
+                outputDir: fullOptions.protoOutputDir,
+            });
+
+            protoPath = path.join(
+                fullOptions.protoOutputDir,
+                `${fullOptions.serviceName.toLowerCase().replace(/service$/, '')}.proto`
+            );
+
+            console.log(`Proto file auto-generated: ${protoPath}`);
+        }
+
+        // Step 2: Load the proto definition
+        const packageDefinition = protoLoader.loadSync(protoPath, {
+            keepCase: false, // Convert snake_case to camelCase
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+        });
+
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+
+        // Step 3: Navigate to the service definition
+        let serviceDefinition: any = protoDescriptor;
+        const packageParts = fullOptions.packageName.split('.');
+        for (const part of packageParts) {
+            serviceDefinition = serviceDefinition[part];
+            if (!serviceDefinition) {
+                throw new Error(`Package '${fullOptions.packageName}' not found in proto`);
+            }
+        }
+
+        const ServiceConstructor = serviceDefinition[fullOptions.serviceName];
+        if (!ServiceConstructor || !ServiceConstructor.service) {
+            throw new Error(`Service '${fullOptions.serviceName}' not found in package '${fullOptions.packageName}'`);
+        }
+
+        // Step 4: Create handler implementations
+        const implementations: Record<string, grpc.handleUnaryCall<any, any>> = {};
+
+        for (const handler of handlers) {
+            // gRPC uses lowercase first letter for method names in implementation
+            const methodName = handler.name.charAt(0).toLowerCase() + handler.name.slice(1);
+
+            implementations[methodName] = async (
+                call: grpc.ServerUnaryCall<any, any>,
+                callback: grpc.sendUnaryData<any>
+            ) => {
+                try {
+                    const result = await handler.handler(call.request);
+                    callback(null, result);
+                } catch (error: any) {
+                    console.error(`gRPC Error in ${handler.name}:`, error);
+                    callback({
+                        code: grpc.status.INTERNAL,
+                        message: error.message || 'Internal server error',
+                    });
+                }
+            };
+        }
+
+        // Step 5: Create and configure the server
+        const server = new grpc.Server();
+        server.addService(ServiceConstructor.service, implementations);
+
+        return new GrpcServerFactory(server, { ...fullOptions, protoPath });
+    }
+
+    /**
+     * Start the gRPC server
+     */
+    async start(): Promise<void> {
+        return new Promise((resolve, reject) => {
+            const address = `${this.options.host}:${this.options.port}`;
+
+            this.server.bindAsync(
+                address,
+                grpc.ServerCredentials.createInsecure(),
+                (error, port) => {
+                    if (error) {
+                        reject(error);
+                        return;
+                    }
+
+                    this.isRunning = true;
+                    console.log(` gRPC Server running on ${address}`);
+                    console.log(`   Service: ${this.options.serviceName}`);
+                    console.log(`   Package: ${this.options.packageName}`);
+                    resolve();
+                }
+            );
+        });
+    }
+
+    /**
+     * Stop the gRPC server
+     */
+    async stop(): Promise<void> {
+        return new Promise((resolve) => {
+            this.server.tryShutdown(() => {
+                this.isRunning = false;
+                console.log('gRPC Server stopped');
+                resolve();
+            });
+        });
+    }
+
+    /**
+     * Force stop the server immediately
+     */
+    forceStop(): void {
+        this.server.forceShutdown();
+        this.isRunning = false;
+        console.log('gRPC Server force stopped');
+    }
+
+    /**
+     * Check if server is running
+     */
+    get running(): boolean {
+        return this.isRunning;
+    }
+
+    /**
+     * Get the server address
+     */
+    get address(): string {
+        return `${this.options.host}:${this.options.port}`;
+    }
+}
+
+/**
+ * Helper function to quickly expose a function as a gRPC service
+ * 
+ * Usage:
+ * ```typescript
+ * const server = await exposeAsGrpc(
+ *   'CalculateFee',
+ *   async (req) => ({ fee: req.amount * 0.02 }),
+ *   { requestSample: () => ({ amount: 100 }), responseSample: () => ({ fee: 2 }) },
+ *   { packageName: 'fee.v1', serviceName: 'FeeService', port: 50053 }
+ * );
+ * ```
+ */
+export async function exposeAsGrpc<TReq extends object, TRes extends object>(
+    methodName: string,
+    handler: (request: TReq) => Promise<TRes> | TRes,
+    samples: { requestSample: () => TReq; responseSample: () => TRes },
+    options: GrpcServerOptions
+): Promise<GrpcServerFactory> {
+    const server = await GrpcServerFactory.createServer(options, [
+        {
+            name: methodName,
+            handler,
+            requestSample: samples.requestSample,
+            responseSample: samples.responseSample,
+        },
+    ]);
+
+    await server.start();
+    return server;
+}

package/src/grpc/types.ts

@@ -0,0 +1,11 @@
+import { ChannelOptions, ChannelCredentials } from '@grpc/grpc-js';
+
+export interface GrpcClientOptions {
+    serviceName: string;
+    packageName?: string;
+    protoPath: string;
+    url: string;
+    credentials?: ChannelCredentials;
+    channelOptions?: ChannelOptions;
+    loaderOptions?: object;
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @themainstack/communication
+ * 
+ * A unified gRPC framework for inter-service communication.
+ * 
+ * Workflow:
+ * 1. Proto Generation - Auto-generate .proto files from TypeScript
+ * 2. Server Factory - Expose functions as gRPC endpoints
+ * 3. Client Factory - Call gRPC services from other services
+ * 4. Error Handling - Standardized error translation
+ */
+
+// Proto Generation
+// Auto-generate .proto files from TypeScript types
+export {
+    generateProtoFromMethods,
+    generateProtoFromFunction
+} from './proto-generator';
+export type {
+    MethodDefinition,
+    GenerateProtoOptions
+} from './proto-generator';
+
+// Server Factory
+// Expose existing functions as gRPC endpoints
+export {
+    GrpcServerFactory,
+    exposeAsGrpc
+} from './grpc/server-factory';
+export type {
+    GrpcServerOptions,
+    ServerMethodHandler
+} from './grpc/server-factory';
+
+// Client Factory
+// Create clients to call gRPC services
+export { GrpcClientFactory } from './grpc/client-factory';
+export type { GrpcClientOptions } from './grpc/types';
+
+// Error Handling
+// Standardized gRPC error translation
+export { handleGrpcError, GrpcError } from './grpc/errors';

package/src/proto-generator/index.ts

@@ -0,0 +1,293 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Maps JavaScript/TypeScript runtime types to Protobuf types.
+ */
+type ProtoType = "double" | "float" | "int32" | "int64" | "bool" | "string" | "bytes" | string;
+
+interface ProtoField {
+    name: string;
+    type: ProtoType;
+    rule?: "repeated";
+    id: number;
+}
+
+interface ProtoMessage {
+    name: string;
+    fields: ProtoField[];
+}
+
+interface ProtoMethod {
+    name: string;
+    requestType: string;
+    responseType: string;
+}
+
+/**
+ * Options for generating a proto file
+ */
+export interface GenerateProtoOptions {
+    /** The package name (e.g., 'fee.v1') */
+    packageName?: string;
+    /** The service name (e.g., 'FeeService') */
+    serviceName?: string;
+    /** Directory to save the proto file (if not provided, won't save to file) */
+    outputDir?: string;
+    /** Output filename (default: derived from serviceName or 'generated.proto') */
+    outputFilename?: string;
+}
+
+/**
+ * Definition of a gRPC method with request and response generators
+ */
+export interface MethodDefinition<TReq extends object, TRes extends object> {
+    /** Method name (e.g., 'CalculateWithdrawalFee') */
+    name: string;
+    /** Function that returns a sample request object */
+    requestSample: () => TReq;
+    /** Function that returns a sample response object */
+    responseSample: () => TRes;
+}
+
+/**
+ * Generate a complete .proto file from method definitions
+ * 
+ * @param methods Array of method definitions
+ * @param options Generation options
+ * @returns The generated proto string
+ */
+export function generateProtoFromMethods(
+    methods: MethodDefinition<any, any>[],
+    options: GenerateProtoOptions = {}
+): string {
+    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename } = options;
+
+    const messages: ProtoMessage[] = [];
+    const protoMethods: ProtoMethod[] = [];
+    const processedObjects = new Set<object>();
+
+    // Helper: Capitalize string
+    function capitalize(s: string): string {
+        return s.charAt(0).toUpperCase() + s.slice(1);
+    }
+
+    // Helper: Convert camelCase to snake_case
+    function toSnakeCase(s: string): string {
+        return s.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+
+    // Recursive function to analyze object and generate messages
+    function analyzeMessage(obj: any, msgName: string): string {
+        if (obj instanceof Date) return "string";
+
+        if (processedObjects.has(obj)) {
+            console.warn(`Circular reference detected for ${msgName}. Breaking recursion.`);
+            return "string";
+        }
+        processedObjects.add(obj);
+
+        const fields: ProtoField[] = [];
+        let fieldIdCounter = 1;
+
+        for (const [key, value] of Object.entries(obj)) {
+            let type: ProtoType = "string";
+            let rule: "repeated" | undefined = undefined;
+
+            const valueType = typeof value;
+
+            if (value === null || value === undefined) {
+                type = "string";
+            } else if (valueType === "string") {
+                type = "string";
+            } else if (valueType === "boolean") {
+                type = "bool";
+            } else if (valueType === "number") {
+                type = Number.isInteger(value) ? "int32" : "double";
+            } else if (Array.isArray(value)) {
+                rule = "repeated";
+                if (value.length > 0) {
+                    const firstItem = value[0];
+                    if (typeof firstItem === "object") {
+                        const nestedName = capitalize(key).replace(/s$/, "");
+                        type = analyzeMessage(firstItem, nestedName);
+                    } else {
+                        type = typeof firstItem === "number"
+                            ? (Number.isInteger(firstItem) ? "int32" : "double")
+                            : typeof firstItem === "boolean" ? "bool" : "string";
+                    }
+                } else {
+                    type = "string";
+                }
+            } else if (valueType === "object") {
+                const nestedName = capitalize(key);
+                type = analyzeMessage(value, nestedName);
+            }
+
+            // Use snake_case for proto fields
+            fields.push({ name: toSnakeCase(key), type, rule, id: fieldIdCounter++ });
+        }
+
+        // Check if message already exists (same name)
+        const existingIndex = messages.findIndex(m => m.name === msgName);
+        if (existingIndex === -1) {
+            messages.push({ name: msgName, fields });
+        }
+
+        return msgName;
+    }
+
+    // Process each method
+    for (const method of methods) {
+        const requestTypeName = `${method.name}Request`;
+        const responseTypeName = `${method.name}Response`;
+
+        // Analyze request and response
+        const requestSample = method.requestSample();
+        const responseSample = method.responseSample();
+
+        analyzeMessage(requestSample, requestTypeName);
+        processedObjects.clear(); // Reset for next analysis
+        analyzeMessage(responseSample, responseTypeName);
+        processedObjects.clear();
+
+        protoMethods.push({
+            name: method.name,
+            requestType: requestTypeName,
+            responseType: responseTypeName,
+        });
+    }
+
+    // Format the proto file
+    const lines: string[] = ['syntax = "proto3";', ''];
+
+    if (packageName) {
+        lines.push(`package ${packageName};`, '');
+    }
+
+    // Service definition
+    lines.push(`// ${serviceName} - Auto-generated gRPC service`);
+    lines.push(`service ${serviceName} {`);
+    for (const method of protoMethods) {
+        lines.push(`  rpc ${method.name} (${method.requestType}) returns (${method.responseType}) {}`);
+    }
+    lines.push('}', '');
+
+    // Message definitions (reverse for proper dependency order)
+    for (const msg of messages.reverse()) {
+        lines.push(`message ${msg.name} {`);
+        for (const field of msg.fields) {
+            const rulePrefix = field.rule ? `${field.rule} ` : "";
+            lines.push(`  ${rulePrefix}${field.type} ${field.name} = ${field.id};`);
+        }
+        lines.push('}', '');
+    }
+
+    const protoContent = lines.join('\n');
+
+    // Save to file if outputDir is specified
+    if (outputDir) {
+        const filename = outputFilename || `${toSnakeCase(serviceName).replace(/_service$/, '')}.proto`;
+        const fullPath = path.join(outputDir, filename);
+
+        // Create directory if it doesn't exist
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        fs.writeFileSync(fullPath, protoContent);
+        console.log(`✅ Proto file generated: ${fullPath}`);
+    }
+
+    return protoContent;
+}
+
+/**
+ * Convenience function for single-function proto generation (original API)
+ */
+export function generateProtoFromFunction<T extends object>(
+    generatorFn: () => T,
+    rootMessageName: string = "RootMessage"
+): string {
+    const messages: ProtoMessage[] = [];
+    const processedObjects = new Set<object>();
+
+    function capitalize(s: string): string {
+        return s.charAt(0).toUpperCase() + s.slice(1);
+    }
+
+    function toSnakeCase(s: string): string {
+        return s.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+
+    function analyzeMessage(obj: any, msgName: string): string {
+        if (obj instanceof Date) return "string";
+
+        if (processedObjects.has(obj)) {
+            return "string";
+        }
+        processedObjects.add(obj);
+
+        const fields: ProtoField[] = [];
+        let fieldIdCounter = 1;
+
+        for (const [key, value] of Object.entries(obj)) {
+            let type: ProtoType = "string";
+            let rule: "repeated" | undefined = undefined;
+
+            const valueType = typeof value;
+
+            if (value === null || value === undefined) {
+                type = "string";
+            } else if (valueType === "string") {
+                type = "string";
+            } else if (valueType === "boolean") {
+                type = "bool";
+            } else if (valueType === "number") {
+                type = Number.isInteger(value) ? "int32" : "double";
+            } else if (Array.isArray(value)) {
+                rule = "repeated";
+                if (value.length > 0) {
+                    const firstItem = value[0];
+                    if (typeof firstItem === "object") {
+                        const nestedName = capitalize(key).replace(/s$/, "");
+                        type = analyzeMessage(firstItem, nestedName);
+                    } else {
+                        type = typeof firstItem === "number"
+                            ? (Number.isInteger(firstItem) ? "int32" : "double")
+                            : typeof firstItem === "boolean" ? "bool" : "string";
+                    }
+                } else {
+                    type = "string";
+                }
+            } else if (valueType === "object") {
+                const nestedName = capitalize(key);
+                type = analyzeMessage(value, nestedName);
+            }
+
+            fields.push({ name: toSnakeCase(key), type, rule, id: fieldIdCounter++ });
+        }
+
+        messages.push({ name: msgName, fields });
+        return msgName;
+    }
+
+    const sampleData = generatorFn();
+    if (!sampleData || typeof sampleData !== "object") {
+        throw new Error("Generator function must return a non-null object.");
+    }
+
+    analyzeMessage(sampleData, rootMessageName);
+
+    const lines: string[] = ['syntax = "proto3";', ''];
+    for (const msg of messages.reverse()) {
+        lines.push(`message ${msg.name} {`);
+        for (const field of msg.fields) {
+            const rulePrefix = field.rule ? `${field.rule} ` : "";
+            lines.push(`  ${rulePrefix}${field.type} ${field.name} = ${field.id};`);
+        }
+        lines.push('}', '');
+    }
+
+    return lines.join('\n');
+}

package/tests/fixtures/dummy.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+package test.v1;
+
+service GreeterService {
+  rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+message HelloRequest {
+  string name = 1;
+}
+
+message HelloReply {
+  string message = 1;
+}

package/tests/fixtures/no-package.proto

@@ -0,0 +1,15 @@
+syntax = "proto3";
+
+// No package definition here
+
+service RootService {
+  rpc SayHello (RootRequest) returns (RootReply) {}
+}
+
+message RootRequest {
+  string name = 1;
+}
+
+message RootReply {
+  string message = 1;
+}

package/tests/grpc/client-factory.spec.ts

@@ -0,0 +1,44 @@
+import { join } from 'path';
+import { describe, it, expect } from 'vitest';
+import * as grpc from '@grpc/grpc-js';
+import { GrpcClientFactory } from '../../src/grpc/client-factory';
+
+describe('GrpcClientFactory', () => {
+    const protoPath = join(__dirname, '../fixtures/dummy.proto');
+    const noPackageProtoPath = join(__dirname, '../fixtures/no-package.proto');
+
+    it('should create a client successfully (Strict Package)', () => {
+        const client = GrpcClientFactory.createClient<grpc.Client>({
+            packageName: 'test.v1',
+            serviceName: 'GreeterService',
+            protoPath,
+            url: 'localhost:50051',
+        });
+        expect(client).toBeDefined();
+        client.close();
+    });
+
+    it('should create a client successfully for ROOT service (Implicit Default)', () => {
+        const client = GrpcClientFactory.createClient<grpc.Client>({
+            // packageName omitted -> defaults to '' (Root)
+            serviceName: 'RootService',
+            protoPath: noPackageProtoPath,
+            url: 'localhost:50051',
+        });
+        expect(client).toBeDefined();
+        client.close();
+    });
+
+    it('should throw error if implicit default fails (expecting root, but service is missing)', () => {
+        // Relying on default '' means looking at root. 
+        // But GreeterService is inside test.v1, so it should NOT be found at root.
+        expect(() => {
+            GrpcClientFactory.createClient<grpc.Client>({
+                // packageName omitted -> defaults to root
+                serviceName: 'GreeterService',
+                protoPath, // This proto puts it in 'test.v1'
+                url: 'localhost:50051',
+            });
+        }).toThrow(/not found in root definition/);
+    });
+});