grpc-powerkit

A powerful and elegant TypeScript-based gRPC server framework with decorators support.

Features

• 🚀 Decorator-based routing and service configuration
• 💪 Strong TypeScript support
• 🛡️ Built-in error handling
• 🔌 Easy service registration

Installation

npm install grpc-powerkit

Quick Start

1. Define your proto file:

syntax = "proto3";

package hello;

service HelloService {
  rpc SayHello (HelloRequest) returns (HelloResponse);
}

message HelloRequest {
  string name = 1;
}

message HelloResponse {
  string message = 1;
}

2. Create your service:

import { GrpcService, GrpcMethod, GrpcError, status } from 'grpc-powerkit';

@GrpcService({
  protoPath: './proto/hello.proto',
  package: 'hello',
  service: 'HelloService'
})
class HelloController {
  @GrpcMethod('HelloService', 'SayHello')
  async sayHello(request: { name: string }) {
    if (!request.name) {
      throw new GrpcError('Name is required', status.INVALID_ARGUMENT);
    }
    return { message: `Hello ${request.name}!` };
  }
}

3. Start the server:

import { GrpcServer } from 'grpc-powerkit';

async function bootstrap() {
  const server = new GrpcServer({
    port: 50051,
    keepCase: true
  });

  server.addController(HelloController);
  await server.start();
}

bootstrap();

API Reference

Decorators

@GrpcService(config: GrpcServiceConfig)

Defines a gRPC service configuration for a controller class.

interface GrpcServiceConfig {
  protoPath: string;     // Path to the proto file
  package: string;       // Proto package name
  service: string;       // Service name
  protoOptions?: Options; // Proto loader options
}

@GrpcMethod(service: string, method: string)

Defines a gRPC method handler.

Classes

GrpcServer

The main server class that handles service registration and lifecycle.

interface GrpcServerConfig {
  port: number;        // Server port
  host?: string;       // Server host (default: '0.0.0.0')
  keepCase?: boolean;  // Keep proto case (default: true)
  secure?: boolean;    // Use secure credentials
}

GrpcError

Custom error class for handling gRPC errors.

new GrpcError(message: string, code: status = status.INTERNAL, details?: any)

Error Handling

The framework provides built-in error handling through the GrpcError class:

throw new GrpcError('Invalid input', status.INVALID_ARGUMENT, { field: 'name' });

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.