Protocol Buffers (protobuf) - TypeScript Code Generation

This directory contains Protocol Buffer definitions for the TeaCinema backend services.

Overview

Protocol Buffers (protobuf) is a method of serializing structured data developed by Google. It's useful for defining APIs and services that communicate over the network.

Prerequisites

Before you can generate TypeScript types from .proto files, ensure you have the following installed:

• protoc (Protocol Buffer Compiler) - Installation Guide
• protoc-gen-ts or protoc-gen-ts_pb (TypeScript code generator)

Installation Steps

Windows

1. Install protoc using Chocolatey (recommended):

   choco install protoc

2. Or download and install manually:

   • Download from protocolbuffers/protobuf releases
   • Extract and add to PATH

3. Install TypeScript protoc plugin:

   npm install --save-dev @protocolbuffers/protobuf
   npm install --save-dev ts-proto

macOS/Linux

# Using Homebrew (macOS)
brew install protobuf

# Using apt (Ubuntu/Debian)
sudo apt-get install protobuf-compiler

# Install TypeScript protoc plugin
npm install --save-dev ts-proto

Project Structure

contracts/
├── proto/
│   ├── auth.proto
│   └── ... (other .proto files)
├── gen/
│   └── ... (auto-generated TypeScript files)
├── package.json
└── README.md

Available Services

AuthService (auth.proto)

Service for authentication-related operations.

SendOtp

Sends an OTP (One-Time Password) to the specified identifier.

Request:

message SendOtpRequest {
  string identifier = 1;  // Email or phone number
  string type = 2;        // OTP type (e.g., "email", "sms")
}

Response:

message SendOtpResponse {
  bool ok = 1;  // Whether the OTP was sent successfully
}

Generating TypeScript Types

Using ts-proto with NestJS Support

This project uses ts-proto to generate TypeScript types with NestJS integration. The generated code is compatible with NestJS microservices.

Quick Start Command

Generate TypeScript types from all .proto files:

npm run generate

Or manually with protoc:

protoc -I ./proto ./proto/*.proto --ts_proto_out=./gen --ts_proto_opt=nestJs=true,package=omit

Command Breakdown

• -I ./proto - Sets the proto files directory as import path
• ./proto/*.proto - Generates from all proto files in the proto directory
• --plugin=protoc-gen-ts_proto - Specifies the ts-proto plugin path
• --ts_proto_out=./gen - Output directory for generated files
• --ts_proto_opt=nestJs=true - Generates NestJS-compatible service interfaces
• --ts_proto_opt=package=omit - Omits package prefix from generated types

Alternative: Using NPM Script

For convenience, use the npm script defined in package.json:

npm run proto:generate

NPM Scripts

Add these scripts to your package.json for easy code generation:

{
  "scripts": {
    "proto:generate": "protoc -I ./proto ./proto/*.proto --plugin=protoc-gen-ts_proto=\"$(pwd)/node_modules/.bin/protoc-gen-ts_proto.cmd\" --ts_proto_out=./gen --ts_proto_opt=nestJs=true,package=omit",
    "proto:clean": "rm -rf gen/*.ts",
    "proto:build": "npm run proto:clean && npm run proto:generate"
  }
}

Then run:

npm run proto:build

Using Generated TypeScript Types

After generation, import and use the types in your TypeScript code:

import { LoginRequest, LoginResponse } from "./generated/proto/auth";

const loginRequest: LoginRequest = {
  email: "[email protected]",
  password: "password123",
};

// Use with gRPC services or REST APIs

Output Options

Common protoc Flags

• --ts_proto_out - Output directory for generated files
• --plugin - Path to the TypeScript code generator plugin
• --proto_path (or -I) - Search path for imported proto files

Example with custom output:

protoc \
  -I=proto \
  --plugin=./node_modules/.bin/protoc-gen-ts_proto \
  --ts_proto_out=./src/generated/proto \
  proto/auth.proto

Workflow Example

1. Define your messages in proto/auth.proto
2. Run generation:

   npm run proto:build

3. Generated files appear in generated/ directory
4. Import and use types in your application

Troubleshooting

"protoc: command not found"

Ensure protoc is installed and added to your PATH:

protoc --version

Plugin not found

Make sure the plugin path is correct and node_modules is installed:

npm install

Permission errors

On macOS/Linux, you may need to make the plugin executable:

chmod +x ./node_modules/.bin/protoc-gen-ts_proto

Resources

• Protocol Buffers Documentation
• ts-proto GitHub
• gRPC-Node Guide
• NestJS gRPC Integration

License

This project uses Protocol Buffers, which is covered under the 3-Clause BSD License.