Where misunderstood Microservices will TypeScript: A Comprehensive Guide

// packages/user-service/src/user.service.ts
// Step 1: Type-safe gRPC User Service with NestJS
import { Injectable, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import { User, CreateUserRequest, CreateUserResponse } from './user.types'; // Generated from proto
import { Logger } from 'nestjs-pino'; // Typed logger
import { Status } from '@grpc/grpc-js/build/src/constants';
import { UserRepository } from './user.repository';

@Injectable()
export class UserService implements OnModuleInit {
  private grpcServer: grpc.Server;
  private userProto: any;

  constructor(
    private readonly configService: ConfigService,
    private readonly logger: Logger,
    private readonly userRepository: UserRepository,
  ) {}

  async onModuleInit() {
    // Load proto file with strict type validation
    const protoPath = this.configService.get('USER_PROTO_PATH');
    if (!protoPath) {
      throw new Error('USER_PROTO_PATH environment variable is not set');
    }

    const packageDef = protoLoader.loadSync(protoPath, {
      keepCase: true,
      longs: String,
      enums: String,
      defaults: true,
      oneofs: true,
      includeDirs: ['.'], // Include proto imports
    });

    this.userProto = grpc.loadPackageDefinition(packageDef).user as any;

    // Initialize gRPC server
    this.grpcServer = new grpc.Server({
      'grpc.max_receive_message_length': 1024 * 1024 * 10, // 10MB max message
      'grpc.keepalive_time_ms': 30000, // 30s keepalive
    });

    // Register service with type-safe handler
    this.grpcServer.addService(this.userProto.UserService.service, {
      createUser: this.createUser.bind(this),
      getUser: this.getUser.bind(this),
    });

    const port = this.configService.get('USER_SERVICE_PORT', 50051);
    const host = this.configService.get('USER_SERVICE_HOST', '0.0.0.0');

    try {
      await new Promise((resolve, reject) => {
        this.grpcServer.bindAsync(
          `${host}:${port}`,
          grpc.ServerCredentials.createInsecure(), // Use TLS in production
          (err, boundPort) => {
            if (err) {
              this.logger.error({ err, port }, 'Failed to bind User Service gRPC server');
              reject(err);
            } else {
              this.logger.info({ boundPort }, 'User Service gRPC server started');
              resolve();
            }
          },
        );
      });
    } catch (error) {
      this.logger.error({ error }, 'User Service startup failed');
      process.exit(1); // Fail fast on startup errors
    }
  }

  // Type-safe gRPC handler with error handling and validation
  private async createUser(
    call: grpc.ServerUnaryCall,
    callback: grpc.sendUnaryData,
  ) {
    const { email, name } = call.request;

    // Validate request (compile-time types + runtime check for edge cases)
    if (!email || !name) {
      return callback({
        code: Status.INVALID_ARGUMENT,
        message: 'Email and name are required',
      });
    }

    try {
      const existingUser = await this.userRepository.findByEmail(email);
      if (existingUser) {
        return callback({
          code: Status.ALREADY_EXISTS,
          message: `User with email ${email} already exists`,
        });
      }

      const newUser: User = await this.userRepository.create({
        email,
        name,
        createdAt: new Date().toISOString(),
      });

      this.logger.info({ userId: newUser.id }, 'User created successfully');

      callback(null, {
        user: newUser,
        success: true,
      });
    } catch (error) {
      this.logger.error({ error, email }, 'Failed to create user');
      callback({
        code: Status.INTERNAL,
        message: 'Internal server error creating user',
      });
    }
  }

  private async getUser(
    call: grpc.ServerUnaryCall<{ id: string }, { user: User | null }>,
    callback: grpc.sendUnaryData<{ user: User | null }>,
  ) {
    const { id } = call.request;
    if (!id) {
      return callback({ code: Status.INVALID_ARGUMENT, message: 'User ID is required' });
    }

    try {
      const user = await this.userRepository.findById(id);
      callback(null, { user });
    } catch (error) {
      this.logger.error({ error, id }, 'Failed to fetch user');
      callback({ code: Status.INTERNAL, message: 'Internal server error fetching user' });
    }
  }
}

// packages/order-service/src/order.service.ts
// Step 2: Order Service with typed async NATS events
import { Injectable, OnModuleInit } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { connect, JetStreamClient, JetStreamPublishOptions, NatsConnection } from 'nats';
import { Logger } from 'nestjs-pino';
import { Order, CreateOrderRequest, OrderCreatedEvent } from './order.types'; // Generated types
import { UserClient } from '../user/user.client'; // gRPC client for User Service
import { ProductClient } from '../product/product.client'; // gRPC client for Product Service
import { OrderRepository } from './order.repository';

@Injectable()
export class OrderService implements OnModuleInit {
  private natsConnection: NatsConnection;
  private jetStream: JetStreamClient;
  private userClient: UserClient;
  private productClient: ProductClient;
  private orderRepository: OrderRepository;

  constructor(
    private readonly configService: ConfigService,
    private readonly logger: Logger,
    userClient: UserClient,
    productClient: ProductClient,
    orderRepository: OrderRepository,
  ) {
    this.userClient = userClient;
    this.productClient = productClient;
    this.orderRepository = orderRepository;
  }

  async onModuleInit() {
    // Connect to NATS JetStream with retry logic
    const natsUrl = this.configService.get('NATS_URL', 'nats://localhost:4222');
    const maxRetries = 5;
    let retryCount = 0;

    while (retryCount < maxRetries) {
      try {
        this.natsConnection = await connect({
          servers: natsUrl,
          reconnect: true,
          maxReconnectAttempts: 10,
          reconnectTimeWait: 1000,
        });
        this.jetStream = this.natsConnection.jetstream();
        this.logger.info({ natsUrl }, 'Connected to NATS JetStream');
        break;
      } catch (error) {
        retryCount++;
        this.logger.warn({ error, retryCount }, 'Failed to connect to NATS, retrying...');
        if (retryCount === maxRetries) {
          this.logger.error({ error }, 'Max NATS retries exceeded');
          process.exit(1);
        }
        await new Promise(resolve => setTimeout(resolve, 2000 * retryCount));
      }
    }

    // Subscribe to order creation events for async processing
    await this.subscribeToOrderEvents();
  }

  // Type-safe order creation with gRPC client calls and event publishing
  async createOrder(request: CreateOrderRequest): Promise {
    const { userId, productId, quantity } = request;

    // Compile-time type check + runtime validation
    if (quantity <= 0) {
      throw new Error('Quantity must be greater than 0');
    }

    // Validate user exists via gRPC (type-safe client)
    let user;
    try {
      user = await this.userClient.getUser({ id: userId });
    } catch (error) {
      this.logger.error({ error, userId }, 'Failed to fetch user for order');
      throw new Error(`User ${userId} not found`);
    }

    // Validate product exists and has stock via gRPC
    let product;
    try {
      product = await this.productClient.getProduct({ id: productId });
      if (product.stock < quantity) {
        throw new Error(`Insufficient stock for product ${productId}`);
      }
    } catch (error) {
      this.logger.error({ error, productId }, 'Failed to fetch product for order');
      throw new Error(`Product ${productId} not found or out of stock`);
    }

    // Create order in DB
    const order: Order = await this.orderRepository.create({
      userId,
      productId,
      quantity,
      total: product.price * quantity,
      status: 'PENDING',
      createdAt: new Date().toISOString(),
    });

    // Publish typed order created event to NATS
    const event: OrderCreatedEvent = {
      orderId: order.id,
      userId,
      productId,
      quantity,
      total: order.total,
      timestamp: new Date().toISOString(),
    };

    const publishOptions: JetStreamPublishOptions = {
      msgID: order.id, // Idempotency key
      expect: { lastSequence: 0 }, // Ensure no duplicate publishes
    };

    try {
      await this.jetStream.publish('order.created', JSON.stringify(event), publishOptions);
      this.logger.info({ orderId: order.id }, 'Order created event published');
    } catch (error) {
      this.logger.error({ error, orderId: order.id }, 'Failed to publish order created event');
      // Roll back order if event publish fails
      await this.orderRepository.updateStatus(order.id, 'FAILED');
      throw new Error('Failed to publish order event');
    }

    return order;
  }

  // Subscribe to order events with typed handlers
  private async subscribeToOrderEvents() {
    const sub = await this.jetStream.subscribe('order.created', {
      max_msgs: 100, // Process 100 messages at a time
      ack_wait: 30000, // 30s to ack
    });

    for await (const msg of sub) {
      const event: OrderCreatedEvent = JSON.parse(msg.data.toString());
      this.logger.info({ orderId: event.orderId }, 'Processing order created event');

      try {
        // Update inventory via gRPC
        await this.productClient.updateStock({
          id: event.productId,
          quantity: -event.quantity,
        });

        // Update order status
        await this.orderRepository.updateStatus(event.orderId, 'CONFIRMED');
        msg.ack();
        this.logger.info({ orderId: event.orderId }, 'Order confirmed');
      } catch (error) {
        this.logger.error({ error, orderId: event.orderId }, 'Failed to process order event');
        msg.nak(); // Retry message
      }
    }
  }
}

// packages/shared/src/tracing.ts
// Step 3: Type-safe OpenTelemetry instrumentation for all services
import { NodeSDK } from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api';
import { Logger } from 'nestjs-pino';

// Enable OpenTelemetry diagnostics only in development
if (process.env.NODE_ENV === 'development') {
  diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.INFO);
}

// Typed resource attributes to avoid typos
interface ServiceResourceAttributes {
  serviceName: string;
  serviceVersion: string;
  environment: string;
  cluster: string;
}

export function initializeTracing(serviceConfig: ServiceResourceAttributes) {
  const logger = new Logger(initializeTracing.name);

  // Validate required config
  if (!serviceConfig.serviceName || !serviceConfig.serviceVersion) {
    throw new Error('serviceName and serviceVersion are required for tracing');
  }

  const resource = new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: serviceConfig.serviceName,
    [SemanticResourceAttributes.SERVICE_VERSION]: serviceConfig.serviceVersion,
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: serviceConfig.environment,
    [SemanticResourceAttributes.CLOUD_REGION]: process.env.AWS_REGION || 'us-east-1',
    'cluster.name': serviceConfig.cluster,
  });

  // Configure OTLP exporter (send to Jaeger/OTEL Collector)
  const traceExporter = new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4317',
    credentials: grpc.credentials.createInsecure(), // Use TLS in production
  });

  const sdk = new NodeSDK({
    resource,
    traceExporter,
    instrumentations: [
      getNodeAutoInstrumentations({
        // Disable instrumentations we don't need
        '@opentelemetry/instrumentation-fs': { enabled: false },
        '@opentelemetry/instrumentation-net': { enabled: false },
        // Enable gRPC and NATS instrumentation
        '@opentelemetry/instrumentation-grpc': { enabled: true },
        '@opentelemetry/instrumentation-nats': { enabled: true },
      }),
    ],
  });

  // Start SDK and handle errors
  try {
    sdk.start();
    logger.info({ serviceName: serviceConfig.serviceName }, 'OpenTelemetry SDK started');
  } catch (error) {
    logger.error({ error }, 'Failed to start OpenTelemetry SDK');
  }

  // Graceful shutdown
  process.on('SIGTERM', async () => {
    try {
      await sdk.shutdown();
      logger.info('OpenTelemetry SDK shut down gracefully');
    } catch (error) {
      logger.error({ error }, 'Error shutting down OpenTelemetry SDK');
    }
  });

  return sdk;
}

// Type-safe span creation helper to avoid untyped span attributes
import { trace, Span, SpanStatusCode } from '@opentelemetry/api';

export function createTypedSpan>(
  spanName: string,
  attributes: T,
  fn: (span: Span) => Promise,
) {
  const tracer = trace.getTracer('microservice-tracer');
  return tracer.startActiveSpan(spanName, async (span: Span) => {
    try {
      // Set typed attributes (compile-time check for attribute keys)
      Object.entries(attributes).forEach(([key, value]) => {
        span.setAttribute(key, value);
      });
      await fn(span);
      span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
      span.setStatus({
        code: SpanStatusCode.ERROR,
        message: error instanceof Error ? error.message : 'Unknown error',
      });
      span.recordException(error instanceof Error ? error : new Error(String(error)));
      throw error;
    } finally {
      span.end();
    }
  });
}

// Generate types from user.proto using ts-proto
// Run: protoc --plugin=protoc-gen-ts=./node_modules/.bin/protoc-gen-ts --ts_out=. user.proto
import { User } from './user'; // Generated type
const user: User = { id: '1', email: 'test@example.com' }; // Compile-time check

// Typed NATS event publisher
import { JetStreamClient } from 'nats';
import { OrderCreatedEvent } from './shared/types';

export class EventPublisher {
  constructor(private readonly jetStream: JetStreamClient) {}

  async publishOrderCreated(event: OrderCreatedEvent) {
    // Compile-time check: event must match OrderCreatedEvent interface
    await this.jetStream.publish('order.created', JSON.stringify(event));
  }
}

// Typed span helper from earlier example
export function createTypedSpan>(
  spanName: string,
  attributes: T,
  fn: (span: Span) => Promise,
) {
  // Compile-time check for attribute types
  const tracer = trace.getTracer('microservice-tracer');
  return tracer.startActiveSpan(spanName, async (span: Span) => { /* ... */ });
}

ts-microservices-definitive-guide/
├── packages/
│   ├── user-service/          # TypeScript gRPC User Service
│   │   ├── src/
│   │   │   ├── user.service.ts
│   │   │   ├── user.client.ts
│   │   │   └── main.ts
│   │   ├── proto/             # Proto definitions
│   │   │   └── user.proto
│   │   ├── tsconfig.json
│   │   └── package.json
│   ├── order-service/         # TypeScript NATS Order Service
│   │   ├── src/
│   │   │   ├── order.service.ts
│   │   │   └── main.ts
│   │   ├── tsconfig.json
│   │   └── package.json
│   ├── product-service/       # TypeScript gRPC Product Service
│   │   └── ...
│   └── shared/                # Shared types and utilities
│       ├── src/
│       │   ├── tracing.ts
│       │   └── types/
│       └── tsconfig.json
├── docker-compose.yml         # Local development environment
├── buf.yaml                   # Proto linting and breaking change config
└── package.json               # Root workspace config