@themainstack/communication 1.0.1 → 1.1.0

package/README.md

@@ -182,6 +182,7 @@ See `examples/full-grpc-demo.ts` in the repository for a complete working exampl
 ### Proto Generation
 - `generateProtoFromMethods(methods, options)` - Generate proto with service definition
 - `generateProtoFromFunction(fn, name)` - Generate proto for a single message
+- `AnyType` - Marker symbol for `google.protobuf.Any` dynamic fields
 
 ### Server
 - `GrpcServerFactory.createServer(options, handlers)` - Create a gRPC server

package/dist/index.d.ts

@@ -9,7 +9,7 @@
  * 3. Client Factory - Call gRPC services from other services
  * 4. Error Handling - Standardized error translation
  */
-export { generateProtoFromMethods, generateProtoFromFunction } from './proto-generator';
+export { generateProtoFromMethods, generateProtoFromFunction, AnyType } from './proto-generator';
 export type { MethodDefinition, GenerateProtoOptions } from './proto-generator';
 export { GrpcServerFactory, exposeAsGrpc } from './grpc/server-factory';
 export type { GrpcServerOptions, ServerMethodHandler } from './grpc/server-factory';

package/dist/index.js

@@ -11,12 +11,13 @@
  * 4. Error Handling - Standardized error translation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GrpcError = exports.handleGrpcError = exports.GrpcClientFactory = exports.exposeAsGrpc = exports.GrpcServerFactory = exports.generateProtoFromFunction = exports.generateProtoFromMethods = void 0;
+exports.GrpcError = exports.handleGrpcError = exports.GrpcClientFactory = exports.exposeAsGrpc = exports.GrpcServerFactory = exports.AnyType = exports.generateProtoFromFunction = exports.generateProtoFromMethods = void 0;
 // Proto Generation
 // Auto-generate .proto files from TypeScript types
 var proto_generator_1 = require("./proto-generator");
 Object.defineProperty(exports, "generateProtoFromMethods", { enumerable: true, get: function () { return proto_generator_1.generateProtoFromMethods; } });
 Object.defineProperty(exports, "generateProtoFromFunction", { enumerable: true, get: function () { return proto_generator_1.generateProtoFromFunction; } });
+Object.defineProperty(exports, "AnyType", { enumerable: true, get: function () { return proto_generator_1.AnyType; } });
 // Server Factory
 // Expose existing functions as gRPC endpoints
 var server_factory_1 = require("./grpc/server-factory");

package/dist/proto-generator/index.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Marker symbol to indicate a field should use google.protobuf.Any type.
+ * Use this in your sample objects to mark dynamic/generic fields.
+ *
+ * @example
+ * requestSample: () => ({ id: '', data: AnyType })
+ */
+export declare const AnyType: unique symbol;
 /**
  * Options for generating a proto file
  */
@@ -10,6 +18,8 @@ export interface GenerateProtoOptions {
     outputDir?: string;
     /** Output filename (default: derived from serviceName or 'generated.proto') */
     outputFilename?: string;
+    /** Enable google.protobuf.Any for dynamic types marked with AnyType symbol (default: true) */
+    enableAnyType?: boolean;
 }
 /**
  * Definition of a gRPC method with request and response generators

package/dist/proto-generator/index.js

@@ -33,10 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnyType = void 0;
 exports.generateProtoFromMethods = generateProtoFromMethods;
 exports.generateProtoFromFunction = generateProtoFromFunction;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+/**
+ * Marker symbol to indicate a field should use google.protobuf.Any type.
+ * Use this in your sample objects to mark dynamic/generic fields.
+ *
+ * @example
+ * requestSample: () => ({ id: '', data: AnyType })
+ */
+exports.AnyType = Symbol('google.protobuf.Any');
 /**
  * Generate a complete .proto file from method definitions
  *
@@ -45,10 +54,11 @@ const path = __importStar(require("path"));
  * @returns The generated proto string
  */
 function generateProtoFromMethods(methods, options = {}) {
-    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename } = options;
+    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename, enableAnyType = true } = options;
     const messages = [];
     const protoMethods = [];
     const processedObjects = new Set();
+    let usesAnyType = false;
     // Helper: Capitalize string
     function capitalize(s) {
         return s.charAt(0).toUpperCase() + s.slice(1);
@@ -72,7 +82,12 @@ function generateProtoFromMethods(methods, options = {}) {
             let type = "string";
             let rule = undefined;
             const valueType = typeof value;
-            if (value === null || value === undefined) {
+            // Check for AnyType marker symbol
+            if (enableAnyType && (value === exports.AnyType || (typeof value === 'symbol' && value.description === 'google.protobuf.Any'))) {
+                type = "google.protobuf.Any";
+                usesAnyType = true;
+            }
+            else if (value === null || value === undefined) {
                 type = "string";
             }
             else if (valueType === "string") {
@@ -89,7 +104,8 @@ function generateProtoFromMethods(methods, options = {}) {
                 if (value.length > 0) {
                     const firstItem = value[0];
                     if (typeof firstItem === "object") {
-                        const nestedName = capitalize(key).replace(/s$/, "");
+                        // Scope nested naming: Parent_Child
+                        const nestedName = `${msgName}_${capitalize(key).replace(/s$/, "")}`;
                         type = analyzeMessage(firstItem, nestedName);
                     }
                     else {
@@ -103,7 +119,8 @@ function generateProtoFromMethods(methods, options = {}) {
                 }
             }
             else if (valueType === "object") {
-                const nestedName = capitalize(key);
+                // Scope nested naming: Parent_Child
+                const nestedName = `${msgName}_${capitalize(key)}`;
                 type = analyzeMessage(value, nestedName);
             }
             // Use snake_case for proto fields
@@ -138,6 +155,10 @@ function generateProtoFromMethods(methods, options = {}) {
     if (packageName) {
         lines.push(`package ${packageName};`, '');
     }
+    // Add google.protobuf.Any import if needed
+    if (usesAnyType) {
+        lines.push('import "google/protobuf/any.proto";', '');
+    }
     // Service definition
     lines.push(`// ${serviceName} - Auto-generated gRPC service`);
     lines.push(`service ${serviceName} {`);

package/docs/INTEGRATION_EXAMPLE.md

@@ -127,6 +127,69 @@ export async function startGrpcServer() {
 }
 ```
 
+### 1.3.1 Organizing Handlers in Separate Files (Recommended)
+
+For services with many gRPC methods, you can keep your code clean by defining handlers in separate files and importing them:
+
+**Step 1: Define handlers in separate files**
+
+```typescript
+// fee-service/src/grpc/handlers/withdrawal-fee.handler.ts
+import { FeesService } from '../../fee/fees.service';
+
+const feesService = new FeesService();
+
+export const withdrawalFeeHandler = {
+  name: 'CalculateWithdrawalFee',
+  handler: async (request: any) => {
+    const result = await feesService.calculateFeesForPlan(
+      'starter',
+      request.currency,
+      request.amount,
+      'withdrawal',
+    );
+    return { /* mapped response */ };
+  },
+  requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
+  responseSample: () => ({ dollarAmount: 0, fee: 0 }),
+};
+```
+
+```typescript
+// fee-service/src/grpc/handlers/deposit-fee.handler.ts
+export const depositFeeHandler = {
+  name: 'CalculateDepositFee',
+  handler: async (request: any) => { /* logic */ },
+  requestSample: () => ({ /* ... */ }),
+  responseSample: () => ({ /* ... */ }),
+};
+```
+
+**Step 2: Import and use them in your bootstrap file**
+
+```typescript
+// fee-service/src/grpc/grpc-bootstrap.ts
+import { GrpcServerFactory } from '@themainstack/communication';
+import { withdrawalFeeHandler } from './handlers/withdrawal-fee.handler';
+import { depositFeeHandler } from './handlers/deposit-fee.handler';
+
+export async function startGrpcServer() {
+  const server = await GrpcServerFactory.createServer({
+    packageName: 'fee.v1',
+    serviceName: 'FeeService',
+    port: parseInt(process.env.GRPC_PORT || '50053'),
+  }, [
+    withdrawalFeeHandler,  // Clean imports!
+    depositFeeHandler,
+  ]);
+
+  await server.start();
+  return server;
+}
+```
+
+This keeps your bootstrap file as a simple **configuration list** while the actual business logic lives in dedicated handler files.
+
 ### 1.4 Integrate with main.ts
 
 ```typescript

package/examples/full-grpc-demo.ts

@@ -47,8 +47,8 @@ async function startServer() {
 
     const server = await GrpcServerFactory.createServer(
         {
-            packageName: 'calculator.v1',
-            serviceName: 'CalculatorService',
+            packageName: 'fee.v1',
+            serviceName: 'FeeService',
             port: 50055,
             protoOutputDir: path.join(__dirname, 'grpc'),
         },
@@ -58,11 +58,11 @@ async function startServer() {
                 handler: calculateFee, // Your existing function!
                 requestSample: () => ({ merchantId: '', amount: 0, currency: '' }),
                 responseSample: () => ({
-                    originalAmount: 0,
-                    fee: 0,
+                    originalAmount: 100,
+                    fee: 10,
                     totalAmount: 0,
-                    currency: '',
-                    feePercentage: 0
+                    currency: 'USD',
+                    feePercentage: 10
                 }),
             },
         ]
@@ -81,8 +81,8 @@ async function callServer() {
     await new Promise(resolve => setTimeout(resolve, 500));
 
     const client = GrpcClientFactory.createClient<any>({
-        serviceName: 'CalculatorService',
-        packageName: 'calculator.v1',
+        serviceName: 'FeeService',
+        packageName: 'fee.v1',
         protoPath: path.join(__dirname, 'grpc', 'calculator.proto'),
         url: 'localhost:50055',
     });
@@ -108,11 +108,6 @@ async function callServer() {
 
 // RUN THE DEMO
 async function main() {
-    console.log('------------------------------------------------------------');
-    console.log('  @themainstack/communication - Full gRPC Demo');
-    console.log('------------------------------------------------------------');
-    console.log('');
-
     // Start server
     const server = await startServer();
 
@@ -130,10 +125,6 @@ async function main() {
         // Stop server
         await server.stop();
     }
-
-    console.log('------------------------------------------------------------');
-    console.log('  Demo Complete!');
-    console.log('------------------------------------------------------------');
 }
 
 main().catch(console.error);

package/examples/grpc/fee.proto

@@ -4,57 +4,19 @@ package fee.v1;
 
 // FeeService - Auto-generated gRPC service
 service FeeService {
-  rpc CalculateWithdrawalFee (CalculateWithdrawalFeeRequest) returns (CalculateWithdrawalFeeResponse) {}
+  rpc CalculateFee (CalculateFeeRequest) returns (CalculateFeeResponse) {}
 }
 
-message CalculateWithdrawalFeeResponse {
-  double dollar_amount = 1;
-  double dollar_transaction_fee = 2;
-  int32 local_transaction_fee = 3;
-  string local_currency = 4;
-  string local_amount = 5;
-  double exchange_rate = 6;
-  repeated AppliedFee applied_fees = 7;
-  repeated string applied_fee_ids = 8;
-  Tax tax = 9;
+message CalculateFeeResponse {
+  int32 original_amount = 1;
+  int32 fee = 2;
+  int32 total_amount = 3;
+  string currency = 4;
+  int32 fee_percentage = 5;
 }
 
-message Tax {
-  string id = 1;
-  double dollar_tax = 2;
-  int32 local_tax = 3;
-  int32 gateway_recorded_tax = 4;
-  int32 surplus_on_gateway_recorded_tax = 5;
-  repeated Breakdown breakdown = 6;
-}
-
-message Breakdown {
-  string country = 1;
-  int32 flat_amount = 2;
-  string percentage_decimal = 3;
-  string rate_type = 4;
-  string state = 5;
-  string tax_type = 6;
-  string taxability_reason = 7;
-}
-
-message AppliedFee {
-  string id = 1;
-  string type = 2;
-  string display_name = 3;
-  double amount = 4;
-  string amount_type = 5;
-  int32 extra = 6;
-  double value = 7;
-  double value_usd = 8;
-  bool is_mainstack = 9;
-  bool is_processor = 10;
-  bool is_deposit = 11;
-}
-
-message CalculateWithdrawalFeeRequest {
+message CalculateFeeRequest {
   string merchant_id = 1;
-  double amount = 2;
+  int32 amount = 2;
   string currency = 3;
-  string payout_method = 4;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@themainstack/communication",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "private": false,
     "description": "Unified gRPC framework for inter-service communication - auto-generates protos, creates servers, and provides type-safe clients",
     "main": "dist/index.js",

package/src/grpc/server-factory.ts

@@ -177,7 +177,7 @@ export class GrpcServerFactory {
             this.server.bindAsync(
                 address,
                 grpc.ServerCredentials.createInsecure(),
-                (error, port) => {
+                (error: Error | null, port: number) => {
                     if (error) {
                         reject(error);
                         return;

package/src/index.ts

@@ -14,7 +14,8 @@
 // Auto-generate .proto files from TypeScript types
 export {
     generateProtoFromMethods,
-    generateProtoFromFunction
+    generateProtoFromFunction,
+    AnyType
 } from './proto-generator';
 export type {
     MethodDefinition,

package/src/proto-generator/index.ts

@@ -1,10 +1,19 @@
 import * as fs from 'fs';
 import * as path from 'path';
 
+/**
+ * Marker symbol to indicate a field should use google.protobuf.Any type.
+ * Use this in your sample objects to mark dynamic/generic fields.
+ * 
+ * @example
+ * requestSample: () => ({ id: '', data: AnyType })
+ */
+export const AnyType = Symbol('google.protobuf.Any');
+
 /**
  * Maps JavaScript/TypeScript runtime types to Protobuf types.
  */
-type ProtoType = "double" | "float" | "int32" | "int64" | "bool" | "string" | "bytes" | string;
+type ProtoType = "double" | "float" | "int32" | "int64" | "bool" | "string" | "bytes" | "google.protobuf.Any" | string;
 
 interface ProtoField {
     name: string;
@@ -36,6 +45,8 @@ export interface GenerateProtoOptions {
     outputDir?: string;
     /** Output filename (default: derived from serviceName or 'generated.proto') */
     outputFilename?: string;
+    /** Enable google.protobuf.Any for dynamic types marked with AnyType symbol (default: true) */
+    enableAnyType?: boolean;
 }
 
 /**
@@ -61,11 +72,12 @@ export function generateProtoFromMethods(
     methods: MethodDefinition<any, any>[],
     options: GenerateProtoOptions = {}
 ): string {
-    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename } = options;
+    const { packageName, serviceName = 'GeneratedService', outputDir, outputFilename, enableAnyType = true } = options;
 
     const messages: ProtoMessage[] = [];
     const protoMethods: ProtoMethod[] = [];
     const processedObjects = new Set<object>();
+    let usesAnyType = false;
 
     // Helper: Capitalize string
     function capitalize(s: string): string {
@@ -96,7 +108,11 @@ export function generateProtoFromMethods(
 
             const valueType = typeof value;
 
-            if (value === null || value === undefined) {
+            // Check for AnyType marker symbol
+            if (enableAnyType && (value === AnyType || (typeof value === 'symbol' && value.description === 'google.protobuf.Any'))) {
+                type = "google.protobuf.Any";
+                usesAnyType = true;
+            } else if (value === null || value === undefined) {
                 type = "string";
             } else if (valueType === "string") {
                 type = "string";
@@ -109,7 +125,8 @@ export function generateProtoFromMethods(
                 if (value.length > 0) {
                     const firstItem = value[0];
                     if (typeof firstItem === "object") {
-                        const nestedName = capitalize(key).replace(/s$/, "");
+                        // Scope nested naming: Parent_Child
+                        const nestedName = `${msgName}_${capitalize(key).replace(/s$/, "")}`;
                         type = analyzeMessage(firstItem, nestedName);
                     } else {
                         type = typeof firstItem === "number"
@@ -120,7 +137,8 @@ export function generateProtoFromMethods(
                     type = "string";
                 }
             } else if (valueType === "object") {
-                const nestedName = capitalize(key);
+                // Scope nested naming: Parent_Child
+                const nestedName = `${msgName}_${capitalize(key)}`;
                 type = analyzeMessage(value, nestedName);
             }
 
@@ -165,6 +183,11 @@ export function generateProtoFromMethods(
         lines.push(`package ${packageName};`, '');
     }
 
+    // Add google.protobuf.Any import if needed
+    if (usesAnyType) {
+        lines.push('import "google/protobuf/any.proto";', '');
+    }
+
     // Service definition
     lines.push(`// ${serviceName} - Auto-generated gRPC service`);
     lines.push(`service ${serviceName} {`);

package/tests/any-type.spec.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { generateProtoFromMethods, AnyType } from '../src/index';
+
+describe('google.protobuf.Any support', () => {
+    it('should export AnyType symbol', () => {
+        expect(AnyType).toBeDefined();
+        expect(typeof AnyType).toBe('symbol');
+        expect(AnyType.description).toBe('google.protobuf.Any');
+    });
+
+    it('should generate proto with google.protobuf.Any for marked fields', () => {
+        const proto = generateProtoFromMethods([
+            {
+                name: 'ProcessGenericData',
+                requestSample: () => ({
+                    id: '',
+                    data: AnyType,
+                }),
+                responseSample: () => ({
+                    success: true,
+                    result: AnyType,
+                }),
+            }
+        ], {
+            packageName: 'generic.v1',
+            serviceName: 'GenericService',
+        });
+
+        // Should include the import statement
+        expect(proto).toContain('import "google/protobuf/any.proto";');
+
+        // Should use google.protobuf.Any type
+        expect(proto).toContain('google.protobuf.Any data = 2;');
+        expect(proto).toContain('google.protobuf.Any result = 2;');
+    });
+
+    it('should not include import if no Any types are used', () => {
+        const proto = generateProtoFromMethods([
+            {
+                name: 'SimpleMethod',
+                requestSample: () => ({ id: '', amount: 0 }),
+                responseSample: () => ({ success: true }),
+            }
+        ], {
+            packageName: 'simple.v1',
+            serviceName: 'SimpleService',
+        });
+
+        expect(proto).not.toContain('import "google/protobuf/any.proto";');
+        expect(proto).not.toContain('google.protobuf.Any');
+    });
+
+    it('should handle mixed fields with some Any types', () => {
+        const proto = generateProtoFromMethods([
+            {
+                name: 'MixedMethod',
+                requestSample: () => ({
+                    id: '',
+                    name: 'test',
+                    metadata: AnyType,
+                    count: 0,
+                }),
+                responseSample: () => ({
+                    status: 'ok',
+                    payload: AnyType,
+                }),
+            }
+        ], {
+            packageName: 'mixed.v1',
+            serviceName: 'MixedService',
+        });
+
+        expect(proto).toContain('import "google/protobuf/any.proto";');
+        expect(proto).toContain('string id = 1;');
+        expect(proto).toContain('string name = 2;');
+        expect(proto).toContain('google.protobuf.Any metadata = 3;');
+        expect(proto).toContain('int32 count = 4;');
+    });
+
+    it('should respect enableAnyType: false option', () => {
+        const proto = generateProtoFromMethods([
+            {
+                name: 'DisabledAny',
+                requestSample: () => ({
+                    id: '',
+                    data: AnyType,
+                }),
+                responseSample: () => ({ success: true }),
+            }
+        ], {
+            packageName: 'test.v1',
+            serviceName: 'TestService',
+            enableAnyType: false,
+        });
+
+        // When disabled, AnyType should be treated as a regular value (string fallback)
+        expect(proto).not.toContain('import "google/protobuf/any.proto";');
+        expect(proto).not.toContain('google.protobuf.Any');
+    });
+});