0
# protobufjs
1

2
protobufjs is a pure JavaScript implementation of Protocol Buffers for JavaScript and TypeScript environments. It provides comprehensive functionality for parsing .proto files, runtime reflection, and efficient binary serialization/deserialization, supporting both Node.js and browser environments with zero native dependencies.
3

4
## Package Information
5

6
- **Package Name**: protobufjs
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install protobufjs`
10

11
## Core Imports
12

13
```javascript
14
// Full build - includes parser and reflection
15
const protobuf = require("protobufjs");
16
```
17

18
```javascript
19
// Light build - reflection without parser  
20
const protobuf = require("protobufjs/light");
21
```
22

23
```javascript
24
// Minimal build - core serialization only
25
const protobuf = require("protobufjs/minimal");
26
```
27

28
ES Module imports:
29

30
```javascript
31
import protobuf from "protobufjs";
32
import * as protobuf from "protobufjs";
33
```
34

35
TypeScript:
36

37
```typescript
38
import * as protobuf from "protobufjs";
39
import { Root, Type, Field, Message } from "protobufjs";
40
```
41

42
## Basic Usage
43

44
```javascript
45
const protobuf = require("protobufjs");
46

47
// Load a .proto file
48
protobuf.load("awesome.proto", function(err, root) {
49
    if (err) throw err;
50

51
    // Obtain a message type
52
    const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
53

54
    // Create a message instance
55
    const payload = { awesomeField: "AwesomeString" };
56
    
57
    // Verify the payload if necessary
58
    const errMsg = AwesomeMessage.verify(payload);
59
    if (errMsg) throw Error(errMsg);
60

61
    // Create and encode a message
62
    const message = AwesomeMessage.create(payload);
63
    const buffer = AwesomeMessage.encode(message).finish();
64

65
    // Decode the message
66
    const decoded = AwesomeMessage.decode(buffer);
67
    console.log(decoded);
68
});
69
```
70

71
## Architecture
72

73
protobufjs is built around several key architectural components:
74

75
- **Build Variants**: Three different builds (full, light, minimal) for different use cases and bundle sizes
76
- **Reflection System**: Runtime representation of .proto definitions with full type information
77
- **Parser**: .proto file parser for dynamic loading and compilation (full build only)
78
- **Code Generation**: Static code generation via CLI tools for optimal performance
79
- **Serialization Engine**: Efficient binary encoding/decoding with type safety
80
- **RPC Framework**: Built-in support for service definitions and RPC implementations
81

82
### Build Variants Comparison
83

84
| Feature | Minimal | Light | Full |
85
|---------|---------|-------|------|
86
| **Bundle Size** | ~6KB | ~16KB | ~26KB |
87
| **Writer/Reader** | ✅ | ✅ | ✅ |
88
| **Message Encoding/Decoding** | ✅ | ✅ | ✅ |
89
| **Root/Type/Field Classes** | ❌ | ✅ | ✅ |
90
| **Runtime Reflection** | ❌ | ✅ | ✅ |
91
| **Dynamic Loading (.proto)** | ❌ | ✅ | ✅ |
92
| **Parser (.proto to JSON)** | ❌ | ❌ | ✅ |
93
| **Tokenizer** | ❌ | ❌ | ✅ |
94
| **Common Google Types** | ❌ | ❌ | ✅ |
95
| **Use Case** | Pre-compiled | Runtime Reflection | Full Development |
96
97
**Choosing a Build:**
98
- **Minimal**: Use with pre-compiled/generated code for smallest bundle size
99
- **Light**: Use when you need runtime reflection but not parsing capabilities  
100
- **Full**: Use for development, dynamic loading, or when parsing .proto files
101

102
## Capabilities
103

104
### Proto File Loading
105

106
Dynamic loading and parsing of .proto files with full reflection support. Enables runtime schema loading and type discovery.
107

108
```javascript { .api }
109
function load(filename: string | string[], callback: LoadCallback): void;
110
function load(filename: string | string[], root: Root, callback: LoadCallback): void;
111
function loadSync(filename: string | string[], root?: Root): Root;
112

113
interface LoadCallback {
114
  (error: Error | null, root?: Root): void;
115
}
116
```
117

118
[Proto Loading](./proto-loading.md)
119

120
### Reflection System
121

122
Complete runtime reflection API for working with protobuf types, services, and schemas. Provides programmatic access to all protobuf constructs.
123

124
```javascript { .api }
125
class Root extends Namespace {
126
  static fromJSON(json: object): Root;
127
  load(filename: string | string[], callback: LoadCallback): Root;
128
  loadSync(filename: string | string[]): Root;
129
}
130

131
class Type extends Namespace {
132
  static fromJSON(name: string, json: object): Type;
133
  create(properties?: object): Message;
134
  encode(message: Message | object): Writer;
135
  decode(reader: Reader | Uint8Array): Message;
136
  verify(message: object): string | null;
137
}
138
```
139

140
[Reflection](./reflection.md)
141

142
### Message Serialization
143

144
High-performance binary serialization and deserialization with full type safety and validation.
145

146
```javascript { .api }
147
class Message {
148
  static create(properties?: object): Message;
149
  static encode(message: Message | object): Writer;
150
  static encodeDelimited(message: Message | object): Writer;
151
  static decode(reader: Reader | Uint8Array): Message;
152
  static decodeDelimited(reader: Reader | Uint8Array): Message;
153
  static verify(message: object): string | null;
154
  static fromObject(object: object): Message;
155
  static toObject(message: Message, options?: IConversionOptions): object;
156
}
157
```
158

159
[Serialization](./serialization.md)
160

161
### Binary I/O Operations
162

163
Low-level binary reading and writing operations for custom serialization needs and performance optimization.
164

165
```javascript { .api }
166
class Writer {
167
  static create(): Writer;
168
  uint32(value: number): Writer;
169
  int32(value: number): Writer;
170
  string(value: string): Writer;
171
  bytes(value: Uint8Array): Writer;
172
  finish(): Uint8Array;
173
}
174

175
class Reader {
176
  static create(buffer: Uint8Array): Reader;
177
  uint32(): number;
178
  int32(): number;
179
  string(): string;
180
  bytes(): Uint8Array;
181
}
182
```
183

184
[Binary I/O](./binary-io.md)
185

186
### Code Generation
187

188
Static code generation and compilation utilities for creating optimized protobuf implementations.
189

190
```javascript { .api }
191
function encoder(mtype: Type): Codegen;
192
function decoder(mtype: Type): Codegen;
193
function verifier(mtype: Type): Codegen;
194

195
namespace converter {
196
  function fromObject(mtype: Type): Codegen;
197
  function toObject(mtype: Type): Codegen;
198
}
199
```
200

201
[Code Generation](./code-generation.md)
202

203
### RPC Services
204

205
Built-in RPC service framework for implementing and consuming protobuf-based services.
206

207
```javascript { .api }
208
class Service extends Namespace {
209
  static fromJSON(name: string, json: object): Service;
210
  create(rpcImpl: RPCImpl, requestDelimited?: boolean, responseDelimited?: boolean): rpc.Service;
211
}
212

213
interface RPCImpl {
214
  (method: Method, requestData: Uint8Array, callback: RPCImplCallback): void;
215
}
216
```
217

218
[RPC Services](./rpc-services.md)
219

220
### Proto Tokenization
221

222
Low-level tokenization of .proto source files for advanced parsing and analysis use cases. Available in full build only.
223

224
```javascript { .api }
225
function tokenize(source: string, alternateCommentMode: boolean): ITokenizerHandle;
226

227
namespace tokenize {
228
  function unescape(str: string): string;
229
}
230

231
interface ITokenizerHandle {
232
  next(): string | null;
233
  peek(): string | null;
234
  push(token: string): void;
235
  skip(expected?: string, optional?: boolean): boolean;
236
  cmnt(trailingLine?: number): string | null;
237
  line: number;
238
}
239
```
240

241
### Google Protocol Buffer Types
242

243
Built-in support for Google's well-known types with automatic handling and type definitions. Available in full build only.
244

245
```javascript { .api }
246
function common(name: string, json: { [k: string]: any }): void;
247

248
namespace common {
249
  function get(file: string): object | null;
250
  
251
  interface IAny {
252
    typeUrl?: string;
253
    bytes?: Uint8Array;
254
  }
255
  
256
  interface IDuration {
257
    seconds?: (number | Long);
258
    nanos?: number;
259
  }
260
  
261
  interface ITimestamp {
262
    seconds?: (number | Long);
263
    nanos?: number;
264
  }
265
  
266
  interface IEmpty {}
267
  
268
  interface IStruct {
269
    fields?: { [k: string]: IValue };
270
  }
271
  
272
  interface IValue {
273
    kind?: string;
274
    nullValue?: 0;
275
    numberValue?: number;
276
    stringValue?: string;
277
    boolValue?: boolean;
278
    structValue?: IStruct;
279
    listValue?: IListValue;
280
  }
281
  
282
  interface IListValue {
283
    values?: IValue[];
284
  }
285
}
286
```
287

288
### CLI Tools
289

290
Command-line utilities for static code generation and TypeScript definition generation.
291

292
```bash { .api }
293
# Generate static JavaScript code
294
pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
295

296
# Generate TypeScript definitions  
297
pbts -o compiled.d.ts compiled.js
298
```
299

300
[CLI Tools](./cli-tools.md)
301

302
### Utility Functions
303

304
Common utility functions for type checking, string manipulation, and low-level operations.
305

306
```javascript { .api }
307
namespace util {
308
  // Type checking utilities
309
  function isInteger(value: any): boolean;
310
  function isString(value: any): boolean;
311
  function isObject(value: any): boolean;
312
  function isSet(obj: object, prop: string): boolean;
313
  
314
  // String manipulation
315
  function lcFirst(str: string): string;
316
  
317
  // Buffer operations  
318
  function newBuffer(sizeOrArray: number | number[]): Uint8Array;
319
  
320
  // Long integer utilities
321
  function longToHash(value: Long | number): string;
322
  function longFromHash(hash: string, unsigned?: boolean): Long;
323
  
324
  // OneOf field helpers
325
  function oneOfGetter(fieldNames: string[]): () => string | undefined;
326
  function oneOfSetter(fieldNames: string[]): (name?: string) => void;
327
  
328
  // Low-level bit manipulation
329
  class LongBits {
330
    constructor(lo: number, hi: number);
331
    lo: number;
332
    hi: number;
333
    static zero: LongBits;
334
    static fromNumber(value: number): LongBits;
335
    static from(value: Long | number | string): LongBits;
336
    toNumber(unsigned?: boolean): number;
337
    toLong(unsigned?: boolean): Long;
338
    zzEncode(): LongBits;
339
    zzDecode(): LongBits;
340
  }
341
}
342
```
343

344
## Types
345

346
```typescript { .api }
347
interface IConversionOptions {
348
  longs?: typeof String | typeof Number | typeof Long;
349
  enums?: typeof String;
350
  bytes?: typeof Array | typeof String;
351
  defaults?: boolean;
352
  arrays?: boolean;
353
  objects?: boolean;
354
  oneofs?: boolean;
355
}
356

357
interface Long {
358
  low: number;
359
  high: number;
360
  unsigned: boolean;
361
  toNumber(): number;
362
  toString(): string;
363
}
364

365
interface LoadCallback {
366
  (error: Error | null, root?: Root): void;
367
}
368

369
interface RPCImplCallback {
370
  (error: Error | null, response?: Uint8Array): void;
371
}
372

373
interface ITokenizerHandle {
374
  next(): string | null;
375
  peek(): string | null;
376
  push(token: string): void;
377
  skip(expected?: string, optional?: boolean): boolean;
378
  cmnt(trailingLine?: number): string | null;
379
  line: number;
380
}
381

382
interface IFetchOptions {
383
  binary?: boolean;
384
  xhr?: boolean;
385
}
386

387
type FetchCallback = (error: Error, contents?: string) => void;
388
type PoolAllocator = (size: number) => Uint8Array;
389
type PoolSlicer = (start: number, end: number) => Uint8Array;
390
```