1<h1><p align="center"><img alt="protobuf.js" src="https://github.com/dcodeIO/protobuf.js/raw/master/pbjs.png" width="120" height="104" /></p></h1> 2<p align="center"><a href="https://npmjs.org/package/protobufjs"><img src="https://img.shields.io/npm/v/protobufjs.svg" alt=""></a> <a href="https://travis-ci.org/dcodeIO/protobuf.js"><img src="https://travis-ci.org/dcodeIO/protobuf.js.svg?branch=master" alt=""></a> <a href="https://npmjs.org/package/protobufjs"><img src="https://img.shields.io/npm/dm/protobufjs.svg" alt=""></a> <a href="https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=dcode%40dcode.io&item_name=Open%20Source%20Software%20Donation&item_number=dcodeIO%2Fprotobuf.js"><img alt="donate ❤" src="https://img.shields.io/badge/donate-❤-ff2244.svg"></a></p> 3 4**Protocol Buffers** are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google ([see](https://developers.google.com/protocol-buffers/)). 5 6**protobuf.js** is a pure JavaScript implementation with [TypeScript](https://www.typescriptlang.org) support for [node.js](https://nodejs.org) and the browser. It's easy to use, blazingly fast and works out of the box with [.proto](https://developers.google.com/protocol-buffers/docs/proto) files! 7 8Contents 9-------- 10 11* [Installation](#installation)<br /> 12 How to include protobuf.js in your project. 13 14* [Usage](#usage)<br /> 15 A brief introduction to using the toolset. 16 17 * [Valid Message](#valid-message) 18 * [Toolset](#toolset)<br /> 19 20* [Examples](#examples)<br /> 21 A few examples to get you started. 22 23 * [Using .proto files](#using-proto-files) 24 * [Using JSON descriptors](#using-json-descriptors) 25 * [Using reflection only](#using-reflection-only) 26 * [Using custom classes](#using-custom-classes) 27 * [Using services](#using-services) 28 * [Usage with TypeScript](#usage-with-typescript)<br /> 29 30* [Command line](#command-line)<br /> 31 How to use the command line utility. 32 33 * [pbjs for JavaScript](#pbjs-for-javascript) 34 * [pbts for TypeScript](#pbts-for-typescript) 35 * [Reflection vs. static code](#reflection-vs-static-code) 36 * [Command line API](#command-line-api)<br /> 37 38* [Additional documentation](#additional-documentation)<br /> 39 A list of available documentation resources. 40 41* [Performance](#performance)<br /> 42 A few internals and a benchmark on performance. 43 44* [Compatibility](#compatibility)<br /> 45 Notes on compatibility regarding browsers and optional libraries. 46 47* [Building](#building)<br /> 48 How to build the library and its components yourself. 49 50Installation 51--------------- 52 53### node.js 54 55``` 56$> npm install protobufjs [--save --save-prefix=~] 57``` 58 59```js 60var protobuf = require("protobufjs"); 61``` 62 63**Note** that this library's versioning scheme is not semver-compatible for historical reasons. For guaranteed backward compatibility, always depend on `~6.A.B` instead of `^6.A.B` (hence the `--save-prefix` above). 64 65### Browsers 66 67Development: 68 69``` 70<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.js"></script> 71``` 72 73Production: 74 75``` 76<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.min.js"></script> 77``` 78 79**Remember** to replace the version tag with the exact [release](https://github.com/dcodeIO/protobuf.js/tags) your project depends upon. 80 81The library supports CommonJS and AMD loaders and also exports globally as `protobuf`. 82 83### Distributions 84 85Where bundle size is a factor, there are additional stripped-down versions of the [full library][dist-full] (~19kb gzipped) available that exclude certain functionality: 86 87* When working with JSON descriptors (i.e. generated by [pbjs](#pbjs-for-javascript)) and/or reflection only, see the [light library][dist-light] (~16kb gzipped) that excludes the parser. CommonJS entry point is: 88 89 ```js 90 var protobuf = require("protobufjs/light"); 91 ``` 92 93* When working with statically generated code only, see the [minimal library][dist-minimal] (~6.5kb gzipped) that also excludes reflection. CommonJS entry point is: 94 95 ```js 96 var protobuf = require("protobufjs/minimal"); 97 ``` 98 99[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist 100[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light 101[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal 102 103Usage 104----- 105 106Because JavaScript is a dynamically typed language, protobuf.js introduces the concept of a **valid message** in order to provide the best possible [performance](#performance) (and, as a side product, proper typings): 107 108### Valid message 109 110> A valid message is an object (1) not missing any required fields and (2) exclusively composed of JS types understood by the wire format writer. 111 112There are two possible types of valid messages and the encoder is able to work with both of these for convenience: 113 114* **Message instances** (explicit instances of message classes with default values on their prototype) always (have to) satisfy the requirements of a valid message by design and 115* **Plain JavaScript objects** that just so happen to be composed in a way satisfying the requirements of a valid message as well. 116 117In a nutshell, the wire format writer understands the following types: 118 119| Field type | Expected JS type (create, encode) | Conversion (fromObject) 120|------------|-----------------------------------|------------------------ 121| s-/u-/int32<br />s-/fixed32 | `number` (32 bit integer) | <code>value | 0</code> if signed<br />`value >>> 0` if unsigned 122| s-/u-/int64<br />s-/fixed64 | `Long`-like (optimal)<br />`number` (53 bit integer) | `Long.fromValue(value)` with long.js<br />`parseInt(value, 10)` otherwise 123| float<br />double | `number` | `Number(value)` 124| bool | `boolean` | `Boolean(value)` 125| string | `string` | `String(value)` 126| bytes | `Uint8Array` (optimal)<br />`Buffer` (optimal under node)<br />`Array.<number>` (8 bit integers) | `base64.decode(value)` if a `string`<br />`Object` with non-zero `.length` is assumed to be buffer-like 127| enum | `number` (32 bit integer) | Looks up the numeric id if a `string` 128| message | Valid message | `Message.fromObject(value)` 129 130* Explicit `undefined` and `null` are considered as not set if the field is optional. 131* Repeated fields are `Array.<T>`. 132* Map fields are `Object.<string,T>` with the key being the string representation of the respective value or an 8 characters long binary hash string for `Long`-likes. 133* Types marked as *optimal* provide the best performance because no conversion step (i.e. number to low and high bits or base64 string to buffer) is required. 134 135### Toolset 136 137With that in mind and again for performance reasons, each message class provides a distinct set of methods with each method doing just one thing. This avoids unnecessary assertions / redundant operations where performance is a concern but also forces a user to perform verification (of plain JavaScript objects that *might* just so happen to be a valid message) explicitly where necessary - for example when dealing with user input. 138 139**Note** that `Message` below refers to any message class. 140 141* **Message.verify**(message: `Object`): `null|string`<br /> 142 verifies that a **plain JavaScript object** satisfies the requirements of a valid message and thus can be encoded without issues. Instead of throwing, it returns the error message as a string, if any. 143 144 ```js 145 var payload = "invalid (not an object)"; 146 var err = AwesomeMessage.verify(payload); 147 if (err) 148 throw Error(err); 149 ``` 150 151* **Message.encode**(message: `Message|Object` [, writer: `Writer`]): `Writer`<br /> 152 encodes a **message instance** or valid **plain JavaScript object**. This method does not implicitly verify the message and it's up to the user to make sure that the payload is a valid message. 153 154 ```js 155 var buffer = AwesomeMessage.encode(message).finish(); 156 ``` 157 158* **Message.encodeDelimited**(message: `Message|Object` [, writer: `Writer`]): `Writer`<br /> 159 works like `Message.encode` but additionally prepends the length of the message as a varint. 160 161* **Message.decode**(reader: `Reader|Uint8Array`): `Message`<br /> 162 decodes a buffer to a **message instance**. If required fields are missing, it throws a `util.ProtocolError` with an `instance` property set to the so far decoded message. If the wire format is invalid, it throws an `Error`. 163 164 ```js 165 try { 166 var decodedMessage = AwesomeMessage.decode(buffer); 167 } catch (e) { 168 if (e instanceof protobuf.util.ProtocolError) { 169 // e.instance holds the so far decoded message with missing required fields 170 } else { 171 // wire format is invalid 172 } 173 } 174 ``` 175 176* **Message.decodeDelimited**(reader: `Reader|Uint8Array`): `Message`<br /> 177 works like `Message.decode` but additionally reads the length of the message prepended as a varint. 178 179* **Message.create**(properties: `Object`): `Message`<br /> 180 creates a new **message instance** from a set of properties that satisfy the requirements of a valid message. Where applicable, it is recommended to prefer `Message.create` over `Message.fromObject` because it doesn't perform possibly redundant conversion. 181 182 ```js 183 var message = AwesomeMessage.create({ awesomeField: "AwesomeString" }); 184 ``` 185 186* **Message.fromObject**(object: `Object`): `Message`<br /> 187 converts any non-valid **plain JavaScript object** to a **message instance** using the conversion steps outlined within the table above. 188 189 ```js 190 var message = AwesomeMessage.fromObject({ awesomeField: 42 }); 191 // converts awesomeField to a string 192 ``` 193 194* **Message.toObject**(message: `Message` [, options: `ConversionOptions`]): `Object`<br /> 195 converts a **message instance** to an arbitrary **plain JavaScript object** for interoperability with other libraries or storage. The resulting plain JavaScript object *might* still satisfy the requirements of a valid message depending on the actual conversion options specified, but most of the time it does not. 196 197 ```js 198 var object = AwesomeMessage.toObject(message, { 199 enums: String, // enums as string names 200 longs: String, // longs as strings (requires long.js) 201 bytes: String, // bytes as base64 encoded strings 202 defaults: true, // includes default values 203 arrays: true, // populates empty arrays (repeated fields) even if defaults=false 204 objects: true, // populates empty objects (map fields) even if defaults=false 205 oneofs: true // includes virtual oneof fields set to the present field's name 206 }); 207 ``` 208 209For reference, the following diagram aims to display relationships between the different methods and the concept of a valid message: 210 211<p align="center"><img alt="Toolset Diagram" src="https://protobufjs.github.io/protobuf.js/toolset.svg" /></p> 212 213> In other words: `verify` indicates that calling `create` or `encode` directly on the plain object will [result in a valid message respectively] succeed. `fromObject`, on the other hand, does conversion from a broader range of plain objects to create valid messages. ([ref](https://github.com/dcodeIO/protobuf.js/issues/748#issuecomment-291925749)) 214 215Examples 216-------- 217 218### Using .proto files 219 220It is possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use (reflection-based) message classes: 221 222```protobuf 223// awesome.proto 224package awesomepackage; 225syntax = "proto3"; 226 227message AwesomeMessage { 228 string awesome_field = 1; // becomes awesomeField 229} 230``` 231 232```js 233protobuf.load("awesome.proto", function(err, root) { 234 if (err) 235 throw err; 236 237 // Obtain a message type 238 var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage"); 239 240 // Exemplary payload 241 var payload = { awesomeField: "AwesomeString" }; 242 243 // Verify the payload if necessary (i.e. when possibly incomplete or invalid) 244 var errMsg = AwesomeMessage.verify(payload); 245 if (errMsg) 246 throw Error(errMsg); 247 248 // Create a new message 249 var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary 250 251 // Encode a message to an Uint8Array (browser) or Buffer (node) 252 var buffer = AwesomeMessage.encode(message).finish(); 253 // ... do something with buffer 254 255 // Decode an Uint8Array (browser) or Buffer (node) to a message 256 var message = AwesomeMessage.decode(buffer); 257 // ... do something with message 258 259 // If the application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited. 260 261 // Maybe convert the message back to a plain object 262 var object = AwesomeMessage.toObject(message, { 263 longs: String, 264 enums: String, 265 bytes: String, 266 // see ConversionOptions 267 }); 268}); 269``` 270 271Additionally, promise syntax can be used by omitting the callback, if preferred: 272 273```js 274protobuf.load("awesome.proto") 275 .then(function(root) { 276 ... 277 }); 278``` 279 280### Using JSON descriptors 281 282The library utilizes JSON descriptors that are equivalent to a .proto definition. For example, the following is identical to the .proto definition seen above: 283 284```json 285// awesome.json 286{ 287 "nested": { 288 "AwesomeMessage": { 289 "fields": { 290 "awesomeField": { 291 "type": "string", 292 "id": 1 293 } 294 } 295 } 296 } 297} 298``` 299 300JSON descriptors closely resemble the internal reflection structure: 301 302| Type (T) | Extends | Type-specific properties 303|--------------------|--------------------|------------------------- 304| *ReflectionObject* | | options 305| *Namespace* | *ReflectionObject* | nested 306| Root | *Namespace* | **nested** 307| Type | *Namespace* | **fields** 308| Enum | *ReflectionObject* | **values** 309| Field | *ReflectionObject* | rule, **type**, **id** 310| MapField | Field | **keyType** 311| OneOf | *ReflectionObject* | **oneof** (array of field names) 312| Service | *Namespace* | **methods** 313| Method | *ReflectionObject* | type, **requestType**, **responseType**, requestStream, responseStream 314 315* **Bold properties** are required. *Italic types* are abstract. 316* `T.fromJSON(name, json)` creates the respective reflection object from a JSON descriptor 317* `T#toJSON()` creates a JSON descriptor from the respective reflection object (its name is used as the key within the parent) 318 319Exclusively using JSON descriptors instead of .proto files enables the use of just the light library (the parser isn't required in this case). 320 321A JSON descriptor can either be loaded the usual way: 322 323```js 324protobuf.load("awesome.json", function(err, root) { 325 if (err) throw err; 326 327 // Continue at "Obtain a message type" above 328}); 329``` 330 331Or it can be loaded inline: 332 333```js 334var jsonDescriptor = require("./awesome.json"); // exemplary for node 335 336var root = protobuf.Root.fromJSON(jsonDescriptor); 337 338// Continue at "Obtain a message type" above 339``` 340 341### Using reflection only 342 343Both the full and the light library include full reflection support. One could, for example, define the .proto definitions seen in the examples above using just reflection: 344 345```js 346... 347var Root = protobuf.Root, 348 Type = protobuf.Type, 349 Field = protobuf.Field; 350 351var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string")); 352 353var root = new Root().define("awesomepackage").add(AwesomeMessage); 354 355// Continue at "Create a new message" above 356... 357``` 358 359Detailed information on the reflection structure is available within the [API documentation](#additional-documentation). 360 361### Using custom classes 362 363Message classes can also be extended with custom functionality and it is also possible to register a custom constructor with a reflected message type: 364 365```js 366... 367 368// Define a custom constructor 369function AwesomeMessage(properties) { 370 // custom initialization code 371 ... 372} 373 374// Register the custom constructor with its reflected type (*) 375root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage; 376 377// Define custom functionality 378AwesomeMessage.customStaticMethod = function() { ... }; 379AwesomeMessage.prototype.customInstanceMethod = function() { ... }; 380 381// Continue at "Create a new message" above 382``` 383 384(*) Besides referencing its reflected type through `AwesomeMessage.$type` and `AwesomeMesage#$type`, the respective custom class is automatically populated with: 385 386* `AwesomeMessage.create` 387* `AwesomeMessage.encode` and `AwesomeMessage.encodeDelimited` 388* `AwesomeMessage.decode` and `AwesomeMessage.decodeDelimited` 389* `AwesomeMessage.verify` 390* `AwesomeMessage.fromObject`, `AwesomeMessage.toObject` and `AwesomeMessage#toJSON` 391 392Afterwards, decoded messages of this type are `instanceof AwesomeMessage`. 393 394Alternatively, it is also possible to reuse and extend the internal constructor if custom initialization code is not required: 395 396```js 397... 398 399// Reuse the internal constructor 400var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor; 401 402// Define custom functionality 403AwesomeMessage.customStaticMethod = function() { ... }; 404AwesomeMessage.prototype.customInstanceMethod = function() { ... }; 405 406// Continue at "Create a new message" above 407``` 408 409### Using services 410 411The library also supports consuming services but it doesn't make any assumptions about the actual transport channel. Instead, a user must provide a suitable RPC implementation, which is an asynchronous function that takes the reflected service method, the binary request and a node-style callback as its parameters: 412 413```js 414function rpcImpl(method, requestData, callback) { 415 // perform the request using an HTTP request or a WebSocket for example 416 var responseData = ...; 417 // and call the callback with the binary response afterwards: 418 callback(null, responseData); 419} 420``` 421 422Below is a working example with a typescript implementation using grpc npm package. 423```ts 424const grpc = require('grpc') 425 426const Client = grpc.makeGenericClientConstructor({}) 427const client = new Client( 428 grpcServerUrl, 429 grpc.credentials.createInsecure() 430) 431 432const rpcImpl = function(method, requestData, callback) { 433 client.makeUnaryRequest( 434 method.name, 435 arg => arg, 436 arg => arg, 437 requestData, 438 callback 439 ) 440} 441``` 442 443Example: 444 445```protobuf 446// greeter.proto 447syntax = "proto3"; 448 449service Greeter { 450 rpc SayHello (HelloRequest) returns (HelloReply) {} 451} 452 453message HelloRequest { 454 string name = 1; 455} 456 457message HelloReply { 458 string message = 1; 459} 460``` 461 462```js 463... 464var Greeter = root.lookup("Greeter"); 465var greeter = Greeter.create(/* see above */ rpcImpl, /* request delimited? */ false, /* response delimited? */ false); 466 467greeter.sayHello({ name: 'you' }, function(err, response) { 468 console.log('Greeting:', response.message); 469}); 470``` 471 472Services also support promises: 473 474```js 475greeter.sayHello({ name: 'you' }) 476 .then(function(response) { 477 console.log('Greeting:', response.message); 478 }); 479``` 480 481There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf.js/blob/master/examples/streaming-rpc.js). 482 483Note that the service API is meant for clients. Implementing a server-side endpoint pretty much always requires transport channel (i.e. http, websocket, etc.) specific code with the only common denominator being that it decodes and encodes messages. 484 485### Usage with TypeScript 486 487The library ships with its own [type definitions](https://github.com/dcodeIO/protobuf.js/blob/master/index.d.ts) and modern editors like [Visual Studio Code](https://code.visualstudio.com/) will automatically detect and use them for code completion. 488 489The npm package depends on [@types/node](https://www.npmjs.com/package/@types/node) because of `Buffer` and [@types/long](https://www.npmjs.com/package/@types/long) because of `Long`. If you are not building for node and/or not using long.js, it should be safe to exclude them manually. 490 491#### Using the JS API 492 493The API shown above works pretty much the same with TypeScript. However, because everything is typed, accessing fields on instances of dynamically generated message classes requires either using bracket-notation (i.e. `message["awesomeField"]`) or explicit casts. Alternatively, it is possible to use a [typings file generated for its static counterpart](#pbts-for-typescript). 494 495```ts 496import { load } from "protobufjs"; // respectively "./node_modules/protobufjs" 497 498load("awesome.proto", function(err, root) { 499 if (err) 500 throw err; 501 502 // example code 503 const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage"); 504 505 let message = AwesomeMessage.create({ awesomeField: "hello" }); 506 console.log(`message = ${JSON.stringify(message)}`); 507 508 let buffer = AwesomeMessage.encode(message).finish(); 509 console.log(`buffer = ${Array.prototype.toString.call(buffer)}`); 510 511 let decoded = AwesomeMessage.decode(buffer); 512 console.log(`decoded = ${JSON.stringify(decoded)}`); 513}); 514``` 515 516#### Using generated static code 517 518If you generated static code to `bundle.js` using the CLI and its type definitions to `bundle.d.ts`, then you can just do: 519 520```ts 521import { AwesomeMessage } from "./bundle.js"; 522 523// example code 524let message = AwesomeMessage.create({ awesomeField: "hello" }); 525let buffer = AwesomeMessage.encode(message).finish(); 526let decoded = AwesomeMessage.decode(buffer); 527``` 528 529#### Using decorators 530 531The library also includes an early implementation of [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html). 532 533**Note** that decorators are an experimental feature in TypeScript and that declaration order is important depending on the JS target. For example, `@Field.d(2, AwesomeArrayMessage)` requires that `AwesomeArrayMessage` has been defined earlier when targeting `ES5`. 534 535```ts 536import { Message, Type, Field, OneOf } from "protobufjs/light"; // respectively "./node_modules/protobufjs/light.js" 537 538export class AwesomeSubMessage extends Message<AwesomeSubMessage> { 539 540 @Field.d(1, "string") 541 public awesomeString: string; 542 543} 544 545export enum AwesomeEnum { 546 ONE = 1, 547 TWO = 2 548} 549 550@Type.d("SuperAwesomeMessage") 551export class AwesomeMessage extends Message<AwesomeMessage> { 552 553 @Field.d(1, "string", "optional", "awesome default string") 554 public awesomeField: string; 555 556 @Field.d(2, AwesomeSubMessage) 557 public awesomeSubMessage: AwesomeSubMessage; 558 559 @Field.d(3, AwesomeEnum, "optional", AwesomeEnum.ONE) 560 public awesomeEnum: AwesomeEnum; 561 562 @OneOf.d("awesomeSubMessage", "awesomeEnum") 563 public which: string; 564 565} 566 567// example code 568let message = new AwesomeMessage({ awesomeField: "hello" }); 569let buffer = AwesomeMessage.encode(message).finish(); 570let decoded = AwesomeMessage.decode(buffer); 571``` 572 573Supported decorators are: 574 575* **Type.d(typeName?: `string`)** *(optional)*<br /> 576 annotates a class as a protobuf message type. If `typeName` is not specified, the constructor's runtime function name is used for the reflected type. 577 578* **Field.d<T>(fieldId: `number`, fieldType: `string | Constructor<T>`, fieldRule?: `"optional" | "required" | "repeated"`, defaultValue?: `T`)**<br /> 579 annotates a property as a protobuf field with the specified id and protobuf type. 580 581* **MapField.d<T extends { [key: string]: any }>(fieldId: `number`, fieldKeyType: `string`, fieldValueType. `string | Constructor<{}>`)**<br /> 582 annotates a property as a protobuf map field with the specified id, protobuf key and value type. 583 584* **OneOf.d<T extends string>(...fieldNames: `string[]`)**<br /> 585 annotates a property as a protobuf oneof covering the specified fields. 586 587Other notes: 588 589* Decorated types reside in `protobuf.roots["decorated"]` using a flat structure, so no duplicate names. 590* Enums are copied to a reflected enum with a generic name on decorator evaluation because referenced enum objects have no runtime name the decorator could use. 591* Default values must be specified as arguments to the decorator instead of using a property initializer for proper prototype behavior. 592* Property names on decorated classes must not be renamed on compile time (i.e. by a minifier) because decorators just receive the original field name as a string. 593 594**ProTip!** Not as pretty, but you can [use decorators in plain JavaScript](https://github.com/dcodeIO/protobuf.js/blob/master/examples/js-decorators.js) as well. 595 596Command line 597------------ 598 599**Note** that moving the CLI to [its own package](./cli) is a work in progress. At the moment, it's still part of the main package. 600 601The command line interface (CLI) can be used to translate between file formats and to generate static code as well as TypeScript definitions. 602 603### pbjs for JavaScript 604 605``` 606Translates between file formats and generates static code. 607 608 -t, --target Specifies the target format. Also accepts a path to require a custom target. 609 610 json JSON representation 611 json-module JSON representation as a module 612 proto2 Protocol Buffers, Version 2 613 proto3 Protocol Buffers, Version 3 614 static Static code without reflection (non-functional on its own) 615 static-module Static code without reflection as a module 616 617 -p, --path Adds a directory to the include path. 618 619 -o, --out Saves to a file instead of writing to stdout. 620 621 --sparse Exports only those types referenced from a main file (experimental). 622 623 Module targets only: 624 625 -w, --wrap Specifies the wrapper to use. Also accepts a path to require a custom wrapper. 626 627 default Default wrapper supporting both CommonJS and AMD 628 commonjs CommonJS wrapper 629 amd AMD wrapper 630 es6 ES6 wrapper (implies --es6) 631 closure A closure adding to protobuf.roots where protobuf is a global 632 633 -r, --root Specifies an alternative protobuf.roots name. 634 635 -l, --lint Linter configuration. Defaults to protobuf.js-compatible rules: 636 637 eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins 638 639 --es6 Enables ES6 syntax (const/let instead of var) 640 641 Proto sources only: 642 643 --keep-case Keeps field casing instead of converting to camel case. 644 645 Static targets only: 646 647 --no-create Does not generate create functions used for reflection compatibility. 648 --no-encode Does not generate encode functions. 649 --no-decode Does not generate decode functions. 650 --no-verify Does not generate verify functions. 651 --no-convert Does not generate convert functions like from/toObject 652 --no-delimited Does not generate delimited encode/decode functions. 653 --no-beautify Does not beautify generated code. 654 --no-comments Does not output any JSDoc comments. 655 656 --force-long Enforces the use of 'Long' for s-/u-/int64 and s-/fixed64 fields. 657 --force-number Enforces the use of 'number' for s-/u-/int64 and s-/fixed64 fields. 658 --force-message Enforces the use of message instances instead of plain objects. 659 660usage: pbjs [options] file1.proto file2.json ... (or pipe) other | pbjs [options] - 661``` 662 663For production environments it is recommended to bundle all your .proto files to a single .json file, which minimizes the number of network requests and avoids any parser overhead (hint: works with just the **light** library): 664 665``` 666$> pbjs -t json file1.proto file2.proto > bundle.json 667``` 668 669Now, either include this file in your final bundle: 670 671```js 672var root = protobuf.Root.fromJSON(require("./bundle.json")); 673``` 674 675or load it the usual way: 676 677```js 678protobuf.load("bundle.json", function(err, root) { 679 ... 680}); 681``` 682 683Generated static code, on the other hand, works with just the **minimal** library. For example 684 685``` 686$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto 687``` 688 689will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`. 690 691**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code. 692 693 694### pbts for TypeScript 695 696``` 697Generates TypeScript definitions from annotated JavaScript files. 698 699 -o, --out Saves to a file instead of writing to stdout. 700 701 -g, --global Name of the global object in browser environments, if any. 702 703 --no-comments Does not output any JSDoc comments. 704 705 Internal flags: 706 707 -n, --name Wraps everything in a module of the specified name. 708 709 -m, --main Whether building the main library without any imports. 710 711usage: pbts [options] file1.js file2.js ... (or) other | pbts [options] - 712``` 713 714Picking up on the example above, the following not only generates static code to a CommonJS module `compiled.js` but also its respective TypeScript definitions to `compiled.d.ts`: 715 716``` 717$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto 718$> pbts -o compiled.d.ts compiled.js 719``` 720 721Additionally, TypeScript definitions of static modules are compatible with their reflection-based counterparts (i.e. as exported by JSON modules), as long as the following conditions are met: 722 7231. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor. 7242. Types, services and enums must start with an uppercase letter to become available as properties of the reflected types as well (i.e. to be able to use `MyMessage.MyEnum` instead of `root.lookup("MyMessage.MyEnum")`). 725 726For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code: 727 728``` 729$> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto 730$> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts - 731``` 732 733### Reflection vs. static code 734 735While using .proto files directly requires the full library respectively pure reflection/JSON the light library, pretty much all code but the relatively short descriptors is shared. 736 737Static code, on the other hand, requires just the minimal library, but generates additional source code without any reflection features. This also implies that there is a break-even point where statically generated code becomes larger than descriptor-based code once the amount of code generated exceeds the size of the full respectively light library. 738 739There is no significant difference performance-wise as the code generated statically is pretty much the same as generated at runtime and both are largely interchangeable as seen in the previous section. 740 741| Source | Library | Advantages | Tradeoffs 742|--------|---------|------------|----------- 743| .proto | full | Easily editable<br />Interoperability with other libraries<br />No compile step | Some parsing and possibly network overhead 744| JSON | light | Easily editable<br />No parsing overhead<br />Single bundle (no network overhead) | protobuf.js specific<br />Has a compile step 745| static | minimal | Works where `eval` access is restricted<br />Fully documented<br />Small footprint for small protos | Can be hard to edit<br />No reflection<br />Has a compile step 746 747### Command line API 748 749Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions: 750 751```js 752var pbjs = require("protobufjs/cli/pbjs"); // or require("protobufjs/cli").pbjs / .pbts 753 754pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) { 755 if (err) 756 throw err; 757 // do something with output 758}); 759``` 760 761Additional documentation 762------------------------ 763 764#### Protocol Buffers 765* [Google's Developer Guide](https://developers.google.com/protocol-buffers/docs/overview) 766 767#### protobuf.js 768* [API Documentation](https://protobufjs.github.io/protobuf.js) 769* [CHANGELOG](https://github.com/dcodeIO/protobuf.js/blob/master/CHANGELOG.md) 770* [Frequently asked questions](https://github.com/dcodeIO/protobuf.js/wiki) on our wiki 771 772#### Community 773* [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow 774 775Performance 776----------- 777The package includes a benchmark that compares protobuf.js performance to native JSON (as far as this is possible) and [Google's JS implementation](https://github.com/google/protobuf/tree/master/js). On an i7-2600K running node 6.9.1 it yields: 778 779``` 780benchmarking encoding performance ... 781 782protobuf.js (reflect) x 541,707 ops/sec ±1.13% (87 runs sampled) 783protobuf.js (static) x 548,134 ops/sec ±1.38% (89 runs sampled) 784JSON (string) x 318,076 ops/sec ±0.63% (93 runs sampled) 785JSON (buffer) x 179,165 ops/sec ±2.26% (91 runs sampled) 786google-protobuf x 74,406 ops/sec ±0.85% (86 runs sampled) 787 788 protobuf.js (static) was fastest 789 protobuf.js (reflect) was 0.9% ops/sec slower (factor 1.0) 790 JSON (string) was 41.5% ops/sec slower (factor 1.7) 791 JSON (buffer) was 67.6% ops/sec slower (factor 3.1) 792 google-protobuf was 86.4% ops/sec slower (factor 7.3) 793 794benchmarking decoding performance ... 795 796protobuf.js (reflect) x 1,383,981 ops/sec ±0.88% (93 runs sampled) 797protobuf.js (static) x 1,378,925 ops/sec ±0.81% (93 runs sampled) 798JSON (string) x 302,444 ops/sec ±0.81% (93 runs sampled) 799JSON (buffer) x 264,882 ops/sec ±0.81% (93 runs sampled) 800google-protobuf x 179,180 ops/sec ±0.64% (94 runs sampled) 801 802 protobuf.js (reflect) was fastest 803 protobuf.js (static) was 0.3% ops/sec slower (factor 1.0) 804 JSON (string) was 78.1% ops/sec slower (factor 4.6) 805 JSON (buffer) was 80.8% ops/sec slower (factor 5.2) 806 google-protobuf was 87.0% ops/sec slower (factor 7.7) 807 808benchmarking combined performance ... 809 810protobuf.js (reflect) x 275,900 ops/sec ±0.78% (90 runs sampled) 811protobuf.js (static) x 290,096 ops/sec ±0.96% (90 runs sampled) 812JSON (string) x 129,381 ops/sec ±0.77% (90 runs sampled) 813JSON (buffer) x 91,051 ops/sec ±0.94% (90 runs sampled) 814google-protobuf x 42,050 ops/sec ±0.85% (91 runs sampled) 815 816 protobuf.js (static) was fastest 817 protobuf.js (reflect) was 4.7% ops/sec slower (factor 1.0) 818 JSON (string) was 55.3% ops/sec slower (factor 2.2) 819 JSON (buffer) was 68.6% ops/sec slower (factor 3.2) 820 google-protobuf was 85.5% ops/sec slower (factor 6.9) 821``` 822 823These results are achieved by 824 825* generating type-specific encoders, decoders, verifiers and converters at runtime 826* configuring the reader/writer interface according to the environment 827* using node-specific functionality where beneficial and, of course 828* avoiding unnecessary operations through splitting up [the toolset](#toolset). 829 830You can also run [the benchmark](https://github.com/dcodeIO/protobuf.js/blob/master/bench/index.js) ... 831 832``` 833$> npm run bench 834``` 835 836and [the profiler](https://github.com/dcodeIO/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node): 837 838``` 839$> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000] 840``` 841 842Note that as of this writing, the benchmark suite performs significantly slower on node 7.2.0 compared to 6.9.1 because moths. 843 844Compatibility 845------------- 846 847* Works in all modern and not-so-modern browsers except IE8. 848* Because the internals of this package do not rely on `google/protobuf/descriptor.proto`, options are parsed and presented literally. 849* If typed arrays are not supported by the environment, plain arrays will be used instead. 850* Support for pre-ES5 environments (except IE8) can be achieved by [using a polyfill](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/polyfill.js). 851* Support for [Content Security Policy](https://w3c.github.io/webappsec-csp/)-restricted environments (like Chrome extensions without [unsafe-eval](https://developer.chrome.com/extensions/contentSecurityPolicy#relaxing-eval)) can be achieved by generating and using static code instead. 852* If a proper way to work with 64 bit values (uint64, int64 etc.) is required, just install [long.js](https://github.com/dcodeIO/long.js) alongside this library. All 64 bit numbers will then be returned as a `Long` instance instead of a possibly unsafe JavaScript number ([see](https://github.com/dcodeIO/long.js)). 853* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/dcodeIO/protobuf.js/tree/master/ext/descriptor) 854 855Building 856-------- 857 858To build the library or its components yourself, clone it from GitHub and install the development dependencies: 859 860``` 861$> git clone https://github.com/dcodeIO/protobuf.js.git 862$> cd protobuf.js 863$> npm install 864``` 865 866Building the respective development and production versions with their respective source maps to `dist/`: 867 868``` 869$> npm run build 870``` 871 872Building the documentation to `docs/`: 873 874``` 875$> npm run docs 876``` 877 878Building the TypeScript definition to `index.d.ts`: 879 880``` 881$> npm run types 882``` 883 884### Browserify integration 885 886By default, protobuf.js integrates into any browserify build-process without requiring any optional modules. Hence: 887 888* If int64 support is required, explicitly require the `long` module somewhere in your project as it will be excluded otherwise. This assumes that a global `require` function is present that protobuf.js can call to obtain the long module. 889 890 If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically: 891 892 ```js 893 var Long = ...; 894 895 protobuf.util.Long = Long; 896 protobuf.configure(); 897 ``` 898 899* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) for reference. 900 901**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause) 902