0
# CLI Tool
1

2
Command-line interface for compiling .proto files directly to JavaScript modules. The CLI tool provides a simple way to generate optimized JavaScript code from protocol buffer schema files.
3

4
## Installation and Usage
5

6
### Global Installation
7

8
```bash
9
npm install -g pbf
10
```
11

12
### Usage
13

14
```typescript { .api }
15
// Command signature
16
pbf <proto_path> [--no-write] [--no-read] [--legacy]
17
```
18

19
### Basic Commands
20

21
```bash
22
# Compile a .proto file to JavaScript (outputs to stdout)
23
pbf example.proto > example.js
24

25
# Compile and save to a file
26
pbf schema.proto --legacy > schema.js
27

28
# Generate only read functions
29
pbf data.proto --no-write > data-reader.js
30

31
# Generate only write functions  
32
pbf data.proto --no-read > data-writer.js
33
```
34

35
## Command Options
36

37
### Option: `--no-write`
38

39
Exclude write functions from the generated code:
40

41
```bash
42
pbf example.proto --no-write > example-reader.js
43
```
44

45
Generated code will only contain read functions:
46
```javascript
47
export function readExample(pbf, end) { /* ... */ }
48
// writeExample function will not be generated
49
```
50

51
### Option: `--no-read`
52

53
Exclude read functions from the generated code:
54

55
```bash
56
pbf example.proto --no-read > example-writer.js  
57
```
58

59
Generated code will only contain write functions:
60
```javascript
61
export function writeExample(obj, pbf) { /* ... */ }
62
// readExample function will not be generated
63
```
64

65
### Option: `--legacy`
66

67
Generate CommonJS module instead of ES6 module:
68

69
```bash
70
pbf example.proto --legacy > example.js
71
```
72

73
**ES6 Module Output (default):**
74
```javascript
75
export function readExample(pbf, end) { /* ... */ }
76
export function writeExample(obj, pbf) { /* ... */ }
77
```
78

79
**CommonJS Output (with --legacy):**
80
```javascript
81
exports.readExample = readExample;
82
function readExample(pbf, end) { /* ... */ }
83

84
exports.writeExample = writeExample;
85
function writeExample(obj, pbf) { /* ... */ }
86
```
87

88
## Examples
89

90
### Basic Proto File
91

92
Given a `person.proto` file:
93
```protobuf
94
syntax = "proto3";
95

96
message Person {
97
    string name = 1;
98
    int32 id = 2;
99
    string email = 3;
100
    repeated string phone_numbers = 4;
101
}
102
```
103

104
Generate JavaScript module:
105
```bash
106
pbf person.proto > person.js
107
```
108

109
Generated `person.js`:
110
```javascript
111
export function readPerson(pbf, end) {
112
    return pbf.readFields(readPersonField, {name: "", id: 0, email: "", phone_numbers: []}, end);
113
}
114
function readPersonField(tag, obj, pbf) {
115
    if (tag === 1) obj.name = pbf.readString();
116
    else if (tag === 2) obj.id = pbf.readVarint();
117
    else if (tag === 3) obj.email = pbf.readString();
118
    else if (tag === 4) obj.phone_numbers.push(pbf.readString());
119
}
120
export function writePerson(obj, pbf) {
121
    if (obj.name) pbf.writeStringField(1, obj.name);
122
    if (obj.id) pbf.writeVarintField(2, obj.id);
123
    if (obj.email) pbf.writeStringField(3, obj.email);
124
    for (const item of obj.phone_numbers) pbf.writeStringField(4, item);
125
}
126
```
127

128
### Complex Schema with Nested Messages
129

130
Given a `addressbook.proto` file:
131
```protobuf
132
syntax = "proto3";
133

134
message AddressBook {
135
    repeated Person people = 1;
136
}
137

138
message Person {
139
    string name = 1;
140
    int32 id = 2;
141
    string email = 3;
142
    repeated PhoneNumber phones = 4;
143
}
144

145
message PhoneNumber {
146
    string number = 1;
147
    PhoneType type = 2;
148
}
149

150
enum PhoneType {
151
    MOBILE = 0;
152
    HOME = 1;
153
    WORK = 2;
154
}
155
```
156

157
Generate with options:
158
```bash
159
pbf addressbook.proto --legacy > addressbook.js
160
```
161

162
The generated code will include:
163
- `readAddressBook` / `writeAddressBook`
164
- `readPerson` / `writePerson`  
165
- `readPhoneNumber` / `writePhoneNumber`
166
- `PhoneType` enum constant
167

168
### Workflow Integration
169

170
Integrate proto compilation into build process:
171

172
**package.json scripts:**
173
```json
174
{
175
  "scripts": {
176
    "build:proto": "pbf schema/data.proto > src/generated/data.js",
177
    "build:proto:types": "pbf schema/data.proto --no-write > src/generated/data-reader.js",
178
    "build": "npm run build:proto && webpack"
179
  }
180
}
181
```
182

183
**Makefile integration:**
184
```makefile
185
src/generated/%.js: schema/%.proto
186
	pbf $< > $@
187

188
build: src/generated/data.js src/generated/user.js
189
	webpack
190
```
191

192
### Development Workflow
193

194
```bash
195
# During development - generate readable code
196
pbf schema.proto > generated.js
197

198
# For production - generate optimized code  
199
pbf schema.proto --no-comments > generated.min.js
200
```
201

202
## Usage with Generated Code
203

204
### Importing Generated Functions
205

206
```typescript
207
// Using generated ES6 module
208
import { readPerson, writePerson } from "./person.js";
209
import Pbf from "pbf";
210

211
// Reading
212
const person = readPerson(new Pbf(buffer));
213

214
// Writing  
215
const pbf = new Pbf();
216
writePerson(person, pbf);
217
const encoded = pbf.finish();
218
```
219

220
### CommonJS Usage
221

222
```javascript
223
// Using generated CommonJS module
224
const { readPerson, writePerson } = require("./person.js");
225
const Pbf = require("pbf");
226

227
// Same usage pattern
228
const person = readPerson(new Pbf(buffer));
229
```
230

231
## Error Handling
232

233
The CLI tool will exit with error codes for various failure conditions:
234

235
```bash
236
# No arguments provided
237
pbf
238
# Error: Usage: pbf [file.proto] [--no-read] [--no-write] [--legacy]
239

240
# Invalid proto file
241
pbf nonexistent.proto  
242
# Error: Cannot read proto file
243

244
# Invalid proto syntax
245
pbf invalid.proto
246
# Error: Proto parsing failed
247
```
248

249
Check exit codes in scripts:
250
```bash
251
if pbf schema.proto > generated.js; then
252
    echo "Compilation successful"
253
else
254
    echo "Compilation failed with exit code $?"
255
    exit 1
256
fi
257
```
258

259
## Dependencies
260

261
The CLI tool requires:
262
- **resolve-protobuf-schema** - For parsing .proto files
263
- **Node.js** - Runtime environment
264

265
Ensure these are available in your environment when using the CLI tool programmatically or in build systems.