@themainstack/communication 1.0.0

package/dist/grpc/client-factory.d.ts

@@ -0,0 +1,5 @@
+import * as grpc from '@grpc/grpc-js';
+import { GrpcClientOptions } from './types';
+export declare class GrpcClientFactory {
+    static createClient<T extends grpc.Client>(options: GrpcClientOptions): T;
+}

package/dist/grpc/client-factory.js

@@ -0,0 +1,73 @@
+"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.GrpcClientFactory = void 0;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+class GrpcClientFactory {
+    static createClient(options) {
+        const packageDefinition = protoLoader.loadSync(options.protoPath, {
+            keepCase: true,
+            longs: String,
+            enums: String,
+            defaults: true,
+            oneofs: true,
+            ...options.loaderOptions,
+        });
+        const protoDescriptor = grpc.loadPackageDefinition(packageDefinition);
+        let serviceDef = protoDescriptor;
+        // Default to empty string (root) if not provided
+        const packageName = options.packageName || '';
+        // Only traverse if packageName is non-empty
+        if (packageName) {
+            const pkgNameParts = packageName.split('.');
+            for (const part of pkgNameParts) {
+                if (serviceDef[part]) {
+                    serviceDef = serviceDef[part];
+                }
+                else {
+                    throw new Error(`Package part '${part}' not found in proto definition`);
+                }
+            }
+        }
+        if (!serviceDef[options.serviceName]) {
+            const location = packageName ? `package '${packageName}'` : 'root definition';
+            throw new Error(`Service '${options.serviceName}' not found in ${location}`);
+        }
+        const ServiceClient = serviceDef[options.serviceName];
+        return new ServiceClient(options.url, options.credentials || grpc.credentials.createInsecure(), options.channelOptions);
+    }
+}
+exports.GrpcClientFactory = GrpcClientFactory;

package/dist/grpc/errors.d.ts

@@ -0,0 +1,8 @@
+import { status } from '@grpc/grpc-js';
+export declare class GrpcError extends Error {
+    code: status;
+    details: string;
+    metadata: any;
+    constructor(code: status, message: string, details?: string, metadata?: any);
+}
+export declare const handleGrpcError: (err: any) => never;

package/dist/grpc/errors.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleGrpcError = exports.GrpcError = void 0;
+const grpc_js_1 = require("@grpc/grpc-js");
+class GrpcError extends Error {
+    constructor(code, message, details, metadata) {
+        super(message);
+        this.name = 'GrpcError';
+        this.code = code;
+        this.details = details || message;
+        this.metadata = metadata;
+    }
+}
+exports.GrpcError = GrpcError;
+const handleGrpcError = (err) => {
+    if (err && (err.code !== undefined || err.message)) {
+        const error = err;
+        // Map gRPC status codes to more friendly errors if needed
+        // For now, we wrap it in our GrpcError
+        throw new GrpcError(error.code ?? grpc_js_1.status.UNKNOWN, error.message || 'Unknown gRPC error', error.details, error.metadata);
+    }
+    throw new GrpcError(grpc_js_1.status.UNKNOWN, 'An unexpected error occurred', JSON.stringify(err));
+};
+exports.handleGrpcError = handleGrpcError;

package/dist/grpc/server-factory.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 declare class GrpcServerFactory {
+    private server;
+    private options;
+    private isRunning;
+    private constructor();
+    /**
+     * Create a new gRPC server with the given handlers
+     */
+    static createServer(options: GrpcServerOptions, handlers: ServerMethodHandler[]): Promise<GrpcServerFactory>;
+    /**
+     * Start the gRPC server
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the gRPC server
+     */
+    stop(): Promise<void>;
+    /**
+     * Force stop the server immediately
+     */
+    forceStop(): void;
+    /**
+     * Check if server is running
+     */
+    get running(): boolean;
+    /**
+     * Get the server address
+     */
+    get address(): string;
+}
+/**
+ * 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 declare 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>;

package/dist/grpc/server-factory.js

@@ -0,0 +1,220 @@
+"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.GrpcServerFactory = void 0;
+exports.exposeAsGrpc = exposeAsGrpc;
+const grpc = __importStar(require("@grpc/grpc-js"));
+const protoLoader = __importStar(require("@grpc/proto-loader"));
+const path = __importStar(require("path"));
+const proto_generator_1 = require("../proto-generator");
+/**
+ * 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();
+ * ```
+ */
+class GrpcServerFactory {
+    constructor(server, options) {
+        this.isRunning = false;
+        this.server = server;
+        this.options = options;
+    }
+    /**
+     * Create a new gRPC server with the given handlers
+     */
+    static async createServer(options, handlers) {
+        const fullOptions = {
+            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 = handlers.map(h => ({
+                name: h.name,
+                requestSample: h.requestSample,
+                responseSample: h.responseSample,
+            }));
+            const protoContent = (0, proto_generator_1.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 = 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 = {};
+        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, callback) => {
+                try {
+                    const result = await handler.handler(call.request);
+                    callback(null, result);
+                }
+                catch (error) {
+                    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() {
+        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() {
+        return new Promise((resolve) => {
+            this.server.tryShutdown(() => {
+                this.isRunning = false;
+                console.log('gRPC Server stopped');
+                resolve();
+            });
+        });
+    }
+    /**
+     * Force stop the server immediately
+     */
+    forceStop() {
+        this.server.forceShutdown();
+        this.isRunning = false;
+        console.log('gRPC Server force stopped');
+    }
+    /**
+     * Check if server is running
+     */
+    get running() {
+        return this.isRunning;
+    }
+    /**
+     * Get the server address
+     */
+    get address() {
+        return `${this.options.host}:${this.options.port}`;
+    }
+}
+exports.GrpcServerFactory = GrpcServerFactory;
+/**
+ * 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 }
+ * );
+ * ```
+ */
+async function exposeAsGrpc(methodName, handler, samples, options) {
+    const server = await GrpcServerFactory.createServer(options, [
+        {
+            name: methodName,
+            handler,
+            requestSample: samples.requestSample,
+            responseSample: samples.responseSample,
+        },
+    ]);
+    await server.start();
+    return server;
+}

package/dist/grpc/types.d.ts

@@ -0,0 +1,10 @@
+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/dist/grpc/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @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
+ */
+export { generateProtoFromMethods, generateProtoFromFunction } 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';
+export { GrpcClientFactory } from './grpc/client-factory';
+export type { GrpcClientOptions } from './grpc/types';
+export { handleGrpcError, GrpcError } from './grpc/errors';

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * @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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GrpcError = exports.handleGrpcError = exports.GrpcClientFactory = exports.exposeAsGrpc = exports.GrpcServerFactory = 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; } });
+// Server Factory
+// Expose existing functions as gRPC endpoints
+var server_factory_1 = require("./grpc/server-factory");
+Object.defineProperty(exports, "GrpcServerFactory", { enumerable: true, get: function () { return server_factory_1.GrpcServerFactory; } });
+Object.defineProperty(exports, "exposeAsGrpc", { enumerable: true, get: function () { return server_factory_1.exposeAsGrpc; } });
+// Client Factory
+// Create clients to call gRPC services
+var client_factory_1 = require("./grpc/client-factory");
+Object.defineProperty(exports, "GrpcClientFactory", { enumerable: true, get: function () { return client_factory_1.GrpcClientFactory; } });
+// Error Handling
+// Standardized gRPC error translation
+var errors_1 = require("./grpc/errors");
+Object.defineProperty(exports, "handleGrpcError", { enumerable: true, get: function () { return errors_1.handleGrpcError; } });
+Object.defineProperty(exports, "GrpcError", { enumerable: true, get: function () { return errors_1.GrpcError; } });

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

@@ -0,0 +1,36 @@
+/**
+ * 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 declare function generateProtoFromMethods(methods: MethodDefinition<any, any>[], options?: GenerateProtoOptions): string;
+/**
+ * Convenience function for single-function proto generation (original API)
+ */
+export declare function generateProtoFromFunction<T extends object>(generatorFn: () => T, rootMessageName?: string): string;