@themainstack/communication 1.0.0

package/dist/proto-generator/index.js

@@ -0,0 +1,250 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateProtoFromMethods = generateProtoFromMethods;
+exports.generateProtoFromFunction = generateProtoFromFunction;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Generate a complete .proto file from method definitions
+ *
+ * @param methods Array of method definitions
+ * @param options Generation options
+ * @returns The generated proto string
+ */
+function generateProtoFromMethods(methods, options = {}) {
+    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename } = options;
+    const messages = [];
+    const protoMethods = [];
+    const processedObjects = new Set();
+    // Helper: Capitalize string
+    function capitalize(s) {
+        return s.charAt(0).toUpperCase() + s.slice(1);
+    }
+    // Helper: Convert camelCase to snake_case
+    function toSnakeCase(s) {
+        return s.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+    // Recursive function to analyze object and generate messages
+    function analyzeMessage(obj, msgName) {
+        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 = [];
+        let fieldIdCounter = 1;
+        for (const [key, value] of Object.entries(obj)) {
+            let type = "string";
+            let rule = 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 = ['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)
+ */
+function generateProtoFromFunction(generatorFn, rootMessageName = "RootMessage") {
+    const messages = [];
+    const processedObjects = new Set();
+    function capitalize(s) {
+        return s.charAt(0).toUpperCase() + s.slice(1);
+    }
+    function toSnakeCase(s) {
+        return s.replace(/([A-Z])/g, '_$1').toLowerCase().replace(/^_/, '');
+    }
+    function analyzeMessage(obj, msgName) {
+        if (obj instanceof Date)
+            return "string";
+        if (processedObjects.has(obj)) {
+            return "string";
+        }
+        processedObjects.add(obj);
+        const fields = [];
+        let fieldIdCounter = 1;
+        for (const [key, value] of Object.entries(obj)) {
+            let type = "string";
+            let rule = 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 = ['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/docs/GRPC_USAGE.md

@@ -0,0 +1,203 @@
+# @themainstack/communication - gRPC Usage Guide
+
+A unified gRPC framework for inter-service communication at Mainstack.
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Step 1: Proto Generation](#step-1-proto-generation)
+4. [Step 2: Creating a gRPC Server](#step-2-creating-a-grpc-server)
+5. [Step 3: Creating a gRPC Client](#step-3-creating-a-grpc-client)
+6. [Step 4: Error Handling](#step-4-error-handling)
+7. [Full Example](#full-example)
+
+---
+
+## Overview
+
+The workflow is simple:
+
+```
+Developer writes TypeScript function
+         ↓
+Package auto-generates .proto file
+         ↓
+Server Factory exposes function as gRPC
+         ↓
+Client Factory in another service calls it
+         ↓
+Error Handler normalizes any errors
+```
+
+---
+
+## Installation
+
+```bash
+npm install @themainstack/communication
+# or
+yarn add @themainstack/communication
+```
+
+---
+
+## Step 1: Proto Generation
+
+Auto-generate `.proto` files from your TypeScript types.
+
+```typescript
+import { generateProtoFromMethods } from '@themainstack/communication';
+
+generateProtoFromMethods([
+  {
+    name: 'CalculateFee',
+    requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+    responseSample: () => ({ fee: 0, total: 0 }),
+  }
+], {
+  packageName: 'fee.v1',
+  serviceName: 'FeeService',
+  outputDir: './src/grpc',
+});
+```
+
+**Output:** `./src/grpc/feeservice.proto` is auto-generated!
+
+---
+
+## Step 2: Creating a gRPC Server
+
+Expose existing functions as gRPC endpoints.
+
+```typescript
+import { GrpcServerFactory } from '@themainstack/communication';
+
+// Your existing business function
+async function calculateFee(request) {
+  return { fee: request.amount * 0.02, total: request.amount * 1.02 };
+}
+
+// Create and start the server
+const server = await GrpcServerFactory.createServer({
+  packageName: 'fee.v1',
+  serviceName: 'FeeService',
+  port: 50053,
+}, [
+  {
+    name: 'CalculateFee',
+    handler: calculateFee,  // Your existing function!
+    requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+    responseSample: () => ({ fee: 0, total: 0 }),
+  }
+]);
+
+await server.start();
+// 🚀 gRPC Server running on 0.0.0.0:50053
+```
+
+### Quick Expose (One-liner)
+
+```typescript
+import { exposeAsGrpc } from '@themainstack/communication';
+
+const server = await exposeAsGrpc(
+  'CalculateFee',
+  calculateFee,
+  { requestSample: () => ({...}), responseSample: () => ({...}) },
+  { packageName: 'fee.v1', serviceName: 'FeeService', port: 50053 }
+);
+```
+
+---
+
+## Step 3: Creating a gRPC Client
+
+Call gRPC services from other services.
+
+```typescript
+import { GrpcClientFactory } from '@themainstack/communication';
+
+const client = GrpcClientFactory.createClient({
+  serviceName: 'FeeService',
+  packageName: 'fee.v1',
+  protoPath: './src/grpc/fee.proto',
+  url: process.env.FEE_SERVICE_URL || 'localhost:50053',
+});
+
+// Make a call
+client.CalculateFee(
+  { merchantId: 'merchant_123', amount: 1000, currency: 'USD' },
+  (err, response) => {
+    if (err) {
+      handleGrpcError(err);
+      return;
+    }
+    console.log('Fee:', response.fee);
+  }
+);
+```
+
+---
+
+## Step 4: Error Handling
+
+Standardized gRPC error translation.
+
+```typescript
+import { handleGrpcError } from '@themainstack/communication';
+
+client.SomeMethod(request, (err, response) => {
+  if (err) {
+    try {
+      handleGrpcError(err); // Throws normalized error
+    } catch (normalizedError) {
+      console.error(normalizedError.message);
+      // Handle based on error type
+    }
+    return;
+  }
+  // Process response
+});
+```
+
+---
+
+## Full Example
+
+See `examples/full-grpc-demo.ts` for a complete working example that:
+1. Defines a business function
+2. Creates a gRPC server (proto auto-generated)
+3. Creates a client and calls the server
+4. Handles the response
+
+Run it:
+```bash
+npx ts-node examples/full-grpc-demo.ts
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `GRPC_PORT` | Port for gRPC server | `50051` |
+| `FEE_SERVICE_URL` | Fee service gRPC address | `localhost:50053` |
+
+---
+
+## API Reference
+
+### Proto Generation
+- `generateProtoFromMethods(methods, options)` - Generate proto with service definition
+- `generateProtoFromFunction(fn, name)` - Generate proto for a single message
+
+### Server
+- `GrpcServerFactory.createServer(options, handlers)` - Create a gRPC server
+- `exposeAsGrpc(name, handler, samples, options)` - Quick one-liner
+
+### Client
+- `GrpcClientFactory.createClient(options)` - Create a gRPC client
+
+### Error Handling
+- `handleGrpcError(err)` - Translate gRPC errors to application errors