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