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)

$3

#### Windows

1. Install protoc using Chocolatey (recommended):

``bash
choco install protoc
`

2. Or download and install manually:

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

3. Install TypeScript protoc plugin:
`bash
npm install --save-dev @protocolbuffers/protobuf
npm install --save-dev ts-proto
`

#### macOS/Linux

`bash


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

$3

Service for authentication-related operations.

#### SendOtp

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

Request:

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

Response:

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

Generating TypeScript Types

$3

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:

`bash
npm run generate
`

Or manually with protoc:

`bash
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

$3

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

`bash
npm run proto:generate
`

NPM Scripts

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

`json
{
"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:

`bash
npm run proto:build
`

Using Generated TypeScript Types

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

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

const loginRequest: LoginRequest = {
email: "user@example.com",
password: "password123",
};

// Use with gRPC services or REST APIs
`

Output Options

$3

- --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:

`bash
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:
`bash
npm run proto:build
`
3. Generated files appear in generated/ directory
4. Import and use types in your application

Troubleshooting

$3

Ensure protoc is installed and added to your PATH:

`bash
protoc --version
`

$3

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

`bash
npm install
`

$3

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

`bash
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.