Package Exports

@hazeljs/grpc
@hazeljs/grpc/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hazeljs/grpc) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@hazeljs/grpc

gRPC Module for HazelJS

RPC server support with decorator-based handlers. Built on @grpc/grpc-js and @grpc/proto-loader.

Features

Decorator-Based API - @GrpcMethod() for declarative RPC handlers
DI Integration - Controllers are resolved from the HazelJS container
Proto Loading - Load .proto files at runtime with configurable options
Unary RPC - Support for request-response RPC methods

Installation

npm install @hazeljs/grpc

Quick Start

1. Define your service in a .proto file

syntax = "proto3";
package hero;

service HeroService {
  rpc FindOne (HeroById) returns (Hero);
}

message HeroById {
  int32 id = 1;
}

message Hero {
  int32 id = 1;
  string name = 2;
}

2. Import GrpcModule and create a controller

import { Injectable } from '@hazeljs/core';
import { GrpcMethod } from '@hazeljs/grpc';
import { join } from 'path';
import { HazelModule } from '@hazeljs/core';
import { GrpcModule } from '@hazeljs/grpc';

@Injectable()
export class HeroGrpcController {
  @GrpcMethod('HeroService', 'FindOne')
  findOne(data: { id: number }) {
    return { id: data.id, name: 'Hero' };
  }
}

@HazelModule({
  imports: [
    GrpcModule.forRoot({
      protoPath: join(__dirname, 'hero.proto'),
      package: 'hero',
      url: '0.0.0.0:50051',
    }),
  ],
  providers: [HeroGrpcController],
})
export class AppModule {}

3. Register handlers and start the gRPC server

import { HazelApp } from '@hazeljs/core';
import { GrpcModule, GrpcServer } from '@hazeljs/grpc';
import { Container } from '@hazeljs/core';
import { AppModule } from './app.module';
import { HeroGrpcController } from './hero.grpc-controller';

async function bootstrap() {
  const app = new HazelApp(AppModule);

  // Register gRPC handlers from controllers
  GrpcModule.registerHandlersFromProviders([HeroGrpcController]);

  // Start HTTP server
  await app.listen(3000);

  // Start gRPC server (runs on separate port)
  const grpcServer = Container.getInstance().resolve(GrpcServer);
  await grpcServer.start();
}

bootstrap();

Configuration

GrpcModule.forRoot({
  protoPath: join(__dirname, 'hero.proto'),  // or ['a.proto', 'b.proto']
  package: 'hero',                             // package name from .proto
  url: '0.0.0.0:50051',                       // bind address (default: 0.0.0.0:50051)
  loader: {                                    // @grpc/proto-loader options
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
  },
  isGlobal: true,                              // global module (default)
});

Async Configuration

GrpcModule.forRootAsync({
  useFactory: async (config: ConfigService) => ({
    protoPath: config.get('GRPC_PROTO_PATH'),
    package: config.get('GRPC_PACKAGE'),
    url: config.get('GRPC_URL'),
  }),
  inject: [ConfigService],
});

@GrpcMethod Decorator

// Explicit service and method name
@GrpcMethod('HeroService', 'FindOne')
findOne(data: { id: number }) {
  return { id: data.id, name: 'Hero' };
}

// Method name defaults to the decorated method name
@GrpcMethod('HeroService')
findOne(data: { id: number }) {
  return { id: data.id, name: 'Hero' };
}

// Async handlers are supported
@GrpcMethod('HeroService', 'FindOne')
async findOne(data: { id: number }) {
  const hero = await this.heroRepository.findById(data.id);
  return hero;
}

API

GrpcModule - Module with forRoot(options), forRootAsync(options), registerHandlersFromProvider(provider), registerHandlersFromProviders(providerClasses)
GrpcServer - Injectable service with configure(options), start(), close(), registerHandlersFromProvider(provider), registerHandlersFromProviders(providerClasses)
GrpcMethod(serviceName, methodName?) - Decorator for RPC method handlers
getGrpcMethodMetadata(target) - Get @GrpcMethod metadata from a class