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>
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/)).
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!
11 * [Installation](#installation)<br />
12 How to include protobuf.js in your project.
14 * [Usage](#usage)<br />
15 A brief introduction to using the toolset.
17 * [Valid Message](#valid-message)
18 * [Toolset](#toolset)<br />
20 * [Examples](#examples)<br />
21 A few examples to get you started.
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 />
30 * [Command line](#command-line)<br />
31 How to use the command line utility.
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 />
38 * [Additional documentation](#additional-documentation)<br />
39 A list of available documentation resources.
41 * [Performance](#performance)<br />
42 A few internals and a benchmark on performance.
44 * [Compatibility](#compatibility)<br />
45 Notes on compatibility regarding browsers and optional libraries.
47 * [Building](#building)<br />
48 How to build the library and its components yourself.
56 $> npm install protobufjs [--save --save-prefix=~]
60 var protobuf = require("protobufjs");
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).
70 <script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.js"></script>
76 <script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.min.js"></script>
79 **Remember** to replace the version tag with the exact [release](https://github.com/dcodeIO/protobuf.js/tags) your project depends upon.
81 The library supports CommonJS and AMD loaders and also exports globally as `protobuf`.
85 Where bundle size is a factor, there are additional stripped-down versions of the [full library][dist-full] (~19kb gzipped) available that exclude certain functionality:
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:
90 var protobuf = require("protobufjs/light");
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:
96 var protobuf = require("protobufjs/minimal");
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
106 Because 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):
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.
112 There are two possible types of valid messages and the encoder is able to work with both of these for convenience:
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.
117 In a nutshell, the wire format writer understands the following types:
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)`
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.
137 With 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.
139 **Note** that `Message` below refers to any message class.
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.
145 var payload = "invalid (not an object)";
146 var err = AwesomeMessage.verify(payload);
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.
155 var buffer = AwesomeMessage.encode(message).finish();
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.
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`.
166 var decodedMessage = AwesomeMessage.decode(buffer);
168 if (e instanceof protobuf.util.ProtocolError) {
169 // e.instance holds the so far decoded message with missing required fields
171 // wire format is invalid
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.
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.
183 var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });
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.
190 var message = AwesomeMessage.fromObject({ awesomeField: 42 });
191 // converts awesomeField to a string
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.
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
209 For reference, the following diagram aims to display relationships between the different methods and the concept of a valid message:
211 <p align="center"><img alt="Toolset Diagram" src="https://protobufjs.github.io/protobuf.js/toolset.svg" /></p>
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))
218 ### Using .proto files
220 It 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:
224 package awesomepackage;
227 message AwesomeMessage {
228 string awesome_field = 1; // becomes awesomeField
233 protobuf.load("awesome.proto", function(err, root) {
237 // Obtain a message type
238 var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
241 var payload = { awesomeField: "AwesomeString" };
243 // Verify the payload if necessary (i.e. when possibly incomplete or invalid)
244 var errMsg = AwesomeMessage.verify(payload);
248 // Create a new message
249 var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary
251 // Encode a message to an Uint8Array (browser) or Buffer (node)
252 var buffer = AwesomeMessage.encode(message).finish();
253 // ... do something with buffer
255 // Decode an Uint8Array (browser) or Buffer (node) to a message
256 var message = AwesomeMessage.decode(buffer);
257 // ... do something with message
259 // If the application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited.
261 // Maybe convert the message back to a plain object
262 var object = AwesomeMessage.toObject(message, {
266 // see ConversionOptions
271 Additionally, promise syntax can be used by omitting the callback, if preferred:
274 protobuf.load("awesome.proto")
275 .then(function(root) {
280 ### Using JSON descriptors
282 The library utilizes JSON descriptors that are equivalent to a .proto definition. For example, the following is identical to the .proto definition seen above:
304 JSON descriptors closely resemble the internal reflection structure:
306 | Type (T) | Extends | Type-specific properties
307 |--------------------|--------------------|-------------------------
308 | *ReflectionObject* | | options
309 | *Namespace* | *ReflectionObject* | nested
310 | Root | *Namespace* | **nested**
311 | Type | *Namespace* | **fields**
312 | Enum | *ReflectionObject* | **values**
313 | Field | *ReflectionObject* | rule, **type**, **id**
314 | MapField | Field | **keyType**
315 | OneOf | *ReflectionObject* | **oneof** (array of field names)
316 | Service | *Namespace* | **methods**
317 | Method | *ReflectionObject* | type, **requestType**, **responseType**, requestStream, responseStream
319 * **Bold properties** are required. *Italic types* are abstract.
320 * `T.fromJSON(name, json)` creates the respective reflection object from a JSON descriptor
321 * `T#toJSON()` creates a JSON descriptor from the respective reflection object (its name is used as the key within the parent)
323 Exclusively using JSON descriptors instead of .proto files enables the use of just the light library (the parser isn't required in this case).
325 A JSON descriptor can either be loaded the usual way:
328 protobuf.load("awesome.json", function(err, root) {
331 // Continue at "Obtain a message type" above
335 Or it can be loaded inline:
338 var jsonDescriptor = require("./awesome.json"); // exemplary for node
340 var root = protobuf.Root.fromJSON(jsonDescriptor);
342 // Continue at "Obtain a message type" above
345 ### Using reflection only
347 Both 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:
351 var Root = protobuf.Root,
352 Type = protobuf.Type,
353 Field = protobuf.Field;
355 var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string"));
357 var root = new Root().define("awesomepackage").add(AwesomeMessage);
359 // Continue at "Create a new message" above
363 Detailed information on the reflection structure is available within the [API documentation](#additional-documentation).
365 ### Using custom classes
367 Message classes can also be extended with custom functionality and it is also possible to register a custom constructor with a reflected message type:
372 // Define a custom constructor
373 function AwesomeMessage(properties) {
374 // custom initialization code
378 // Register the custom constructor with its reflected type (*)
379 root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
381 // Define custom functionality
382 AwesomeMessage.customStaticMethod = function() { ... };
383 AwesomeMessage.prototype.customInstanceMethod = function() { ... };
385 // Continue at "Create a new message" above
388 (*) Besides referencing its reflected type through `AwesomeMessage.$type` and `AwesomeMesage#$type`, the respective custom class is automatically populated with:
390 * `AwesomeMessage.create`
391 * `AwesomeMessage.encode` and `AwesomeMessage.encodeDelimited`
392 * `AwesomeMessage.decode` and `AwesomeMessage.decodeDelimited`
393 * `AwesomeMessage.verify`
394 * `AwesomeMessage.fromObject`, `AwesomeMessage.toObject` and `AwesomeMessage#toJSON`
396 Afterwards, decoded messages of this type are `instanceof AwesomeMessage`.
398 Alternatively, it is also possible to reuse and extend the internal constructor if custom initialization code is not required:
403 // Reuse the internal constructor
404 var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor;
406 // Define custom functionality
407 AwesomeMessage.customStaticMethod = function() { ... };
408 AwesomeMessage.prototype.customInstanceMethod = function() { ... };
410 // Continue at "Create a new message" above
415 The 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:
418 function rpcImpl(method, requestData, callback) {
419 // perform the request using an HTTP request or a WebSocket for example
420 var responseData = ...;
421 // and call the callback with the binary response afterwards:
422 callback(null, responseData);
426 Below is a working example with a typescript implementation using grpc npm package.
428 const grpc = require('grpc')
430 const Client = grpc.makeGenericClientConstructor({})
431 const client = new Client(
433 grpc.credentials.createInsecure()
436 const rpcImpl = function(method, requestData, callback) {
437 client.makeUnaryRequest(
454 rpc SayHello (HelloRequest) returns (HelloReply) {}
457 message HelloRequest {
468 var Greeter = root.lookup("Greeter");
469 var greeter = Greeter.create(/* see above */ rpcImpl, /* request delimited? */ false, /* response delimited? */ false);
471 greeter.sayHello({ name: 'you' }, function(err, response) {
472 console.log('Greeting:', response.message);
476 Services also support promises:
479 greeter.sayHello({ name: 'you' })
480 .then(function(response) {
481 console.log('Greeting:', response.message);
485 There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf.js/blob/master/examples/streaming-rpc.js).
487 Note 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.
489 ### Usage with TypeScript
491 The 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.
493 The 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.
495 #### Using the JS API
497 The 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).
500 import { load } from "protobufjs"; // respectively "./node_modules/protobufjs"
502 load("awesome.proto", function(err, root) {
507 const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
509 let message = AwesomeMessage.create({ awesomeField: "hello" });
510 console.log(`message = ${JSON.stringify(message)}`);
512 let buffer = AwesomeMessage.encode(message).finish();
513 console.log(`buffer = ${Array.prototype.toString.call(buffer)}`);
515 let decoded = AwesomeMessage.decode(buffer);
516 console.log(`decoded = ${JSON.stringify(decoded)}`);
520 #### Using generated static code
522 If you generated static code to `bundle.js` using the CLI and its type definitions to `bundle.d.ts`, then you can just do:
525 import { AwesomeMessage } from "./bundle.js";
528 let message = AwesomeMessage.create({ awesomeField: "hello" });
529 let buffer = AwesomeMessage.encode(message).finish();
530 let decoded = AwesomeMessage.decode(buffer);
533 #### Using decorators
535 The library also includes an early implementation of [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
537 **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`.
540 import { Message, Type, Field, OneOf } from "protobufjs/light"; // respectively "./node_modules/protobufjs/light.js"
542 export class AwesomeSubMessage extends Message<AwesomeSubMessage> {
544 @Field.d(1, "string")
545 public awesomeString: string;
549 export enum AwesomeEnum {
554 @Type.d("SuperAwesomeMessage")
555 export class AwesomeMessage extends Message<AwesomeMessage> {
557 @Field.d(1, "string", "optional", "awesome default string")
558 public awesomeField: string;
560 @Field.d(2, AwesomeSubMessage)
561 public awesomeSubMessage: AwesomeSubMessage;
563 @Field.d(3, AwesomeEnum, "optional", AwesomeEnum.ONE)
564 public awesomeEnum: AwesomeEnum;
566 @OneOf.d("awesomeSubMessage", "awesomeEnum")
567 public which: string;
572 let message = new AwesomeMessage({ awesomeField: "hello" });
573 let buffer = AwesomeMessage.encode(message).finish();
574 let decoded = AwesomeMessage.decode(buffer);
577 Supported decorators are:
579 * **Type.d(typeName?: `string`)** *(optional)*<br />
580 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.
582 * **Field.d<T>(fieldId: `number`, fieldType: `string | Constructor<T>`, fieldRule?: `"optional" | "required" | "repeated"`, defaultValue?: `T`)**<br />
583 annotates a property as a protobuf field with the specified id and protobuf type.
585 * **MapField.d<T extends { [key: string]: any }>(fieldId: `number`, fieldKeyType: `string`, fieldValueType. `string | Constructor<{}>`)**<br />
586 annotates a property as a protobuf map field with the specified id, protobuf key and value type.
588 * **OneOf.d<T extends string>(...fieldNames: `string[]`)**<br />
589 annotates a property as a protobuf oneof covering the specified fields.
593 * Decorated types reside in `protobuf.roots["decorated"]` using a flat structure, so no duplicate names.
594 * 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.
595 * Default values must be specified as arguments to the decorator instead of using a property initializer for proper prototype behavior.
596 * 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.
598 **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.
603 **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.
605 The command line interface (CLI) can be used to translate between file formats and to generate static code as well as TypeScript definitions.
607 ### pbjs for JavaScript
610 Translates between file formats and generates static code.
612 -t, --target Specifies the target format. Also accepts a path to require a custom target.
614 json JSON representation
615 json-module JSON representation as a module
616 proto2 Protocol Buffers, Version 2
617 proto3 Protocol Buffers, Version 3
618 static Static code without reflection (non-functional on its own)
619 static-module Static code without reflection as a module
621 -p, --path Adds a directory to the include path.
623 -o, --out Saves to a file instead of writing to stdout.
625 --sparse Exports only those types referenced from a main file (experimental).
629 -w, --wrap Specifies the wrapper to use. Also accepts a path to require a custom wrapper.
631 default Default wrapper supporting both CommonJS and AMD
632 commonjs CommonJS wrapper
634 es6 ES6 wrapper (implies --es6)
635 closure A closure adding to protobuf.roots where protobuf is a global
637 -r, --root Specifies an alternative protobuf.roots name.
639 -l, --lint Linter configuration. Defaults to protobuf.js-compatible rules:
641 eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins
643 --es6 Enables ES6 syntax (const/let instead of var)
647 --keep-case Keeps field casing instead of converting to camel case.
651 --no-create Does not generate create functions used for reflection compatibility.
652 --no-encode Does not generate encode functions.
653 --no-decode Does not generate decode functions.
654 --no-verify Does not generate verify functions.
655 --no-convert Does not generate convert functions like from/toObject
656 --no-delimited Does not generate delimited encode/decode functions.
657 --no-beautify Does not beautify generated code.
658 --no-comments Does not output any JSDoc comments.
660 --force-long Enforces the use of 'Long' for s-/u-/int64 and s-/fixed64 fields.
661 --force-number Enforces the use of 'number' for s-/u-/int64 and s-/fixed64 fields.
662 --force-message Enforces the use of message instances instead of plain objects.
664 usage: pbjs [options] file1.proto file2.json ... (or pipe) other | pbjs [options] -
667 For 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):
670 $> pbjs -t json file1.proto file2.proto > bundle.json
673 Now, either include this file in your final bundle:
676 var root = protobuf.Root.fromJSON(require("./bundle.json"));
679 or load it the usual way:
682 protobuf.load("bundle.json", function(err, root) {
687 Generated static code, on the other hand, works with just the **minimal** library. For example
690 $> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
693 will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`.
695 **ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code.
698 ### pbts for TypeScript
701 Generates TypeScript definitions from annotated JavaScript files.
703 -o, --out Saves to a file instead of writing to stdout.
705 -g, --global Name of the global object in browser environments, if any.
707 --no-comments Does not output any JSDoc comments.
711 -n, --name Wraps everything in a module of the specified name.
713 -m, --main Whether building the main library without any imports.
715 usage: pbts [options] file1.js file2.js ... (or) other | pbts [options] -
718 Picking 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`:
721 $> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
722 $> pbts -o compiled.d.ts compiled.js
725 Additionally, 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:
727 1. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor.
728 2. 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")`).
730 For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code:
733 $> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto
734 $> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts -
737 ### Reflection vs. static code
739 While 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.
741 Static 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.
743 There 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.
745 | Source | Library | Advantages | Tradeoffs
746 |--------|---------|------------|-----------
747 | .proto | full | Easily editable<br />Interoperability with other libraries<br />No compile step | Some parsing and possibly network overhead
748 | JSON | light | Easily editable<br />No parsing overhead<br />Single bundle (no network overhead) | protobuf.js specific<br />Has a compile step
749 | 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
753 Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions:
756 var pbjs = require("protobufjs/cli/pbjs"); // or require("protobufjs/cli").pbjs / .pbts
758 pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) {
761 // do something with output
765 Additional documentation
766 ------------------------
768 #### Protocol Buffers
769 * [Google's Developer Guide](https://developers.google.com/protocol-buffers/docs/overview)
772 * [API Documentation](https://protobufjs.github.io/protobuf.js)
773 * [CHANGELOG](https://github.com/dcodeIO/protobuf.js/blob/master/CHANGELOG.md)
774 * [Frequently asked questions](https://github.com/dcodeIO/protobuf.js/wiki) on our wiki
777 * [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow
781 The 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:
784 benchmarking encoding performance ...
786 protobuf.js (reflect) x 541,707 ops/sec ±1.13% (87 runs sampled)
787 protobuf.js (static) x 548,134 ops/sec ±1.38% (89 runs sampled)
788 JSON (string) x 318,076 ops/sec ±0.63% (93 runs sampled)
789 JSON (buffer) x 179,165 ops/sec ±2.26% (91 runs sampled)
790 google-protobuf x 74,406 ops/sec ±0.85% (86 runs sampled)
792 protobuf.js (static) was fastest
793 protobuf.js (reflect) was 0.9% ops/sec slower (factor 1.0)
794 JSON (string) was 41.5% ops/sec slower (factor 1.7)
795 JSON (buffer) was 67.6% ops/sec slower (factor 3.1)
796 google-protobuf was 86.4% ops/sec slower (factor 7.3)
798 benchmarking decoding performance ...
800 protobuf.js (reflect) x 1,383,981 ops/sec ±0.88% (93 runs sampled)
801 protobuf.js (static) x 1,378,925 ops/sec ±0.81% (93 runs sampled)
802 JSON (string) x 302,444 ops/sec ±0.81% (93 runs sampled)
803 JSON (buffer) x 264,882 ops/sec ±0.81% (93 runs sampled)
804 google-protobuf x 179,180 ops/sec ±0.64% (94 runs sampled)
806 protobuf.js (reflect) was fastest
807 protobuf.js (static) was 0.3% ops/sec slower (factor 1.0)
808 JSON (string) was 78.1% ops/sec slower (factor 4.6)
809 JSON (buffer) was 80.8% ops/sec slower (factor 5.2)
810 google-protobuf was 87.0% ops/sec slower (factor 7.7)
812 benchmarking combined performance ...
814 protobuf.js (reflect) x 275,900 ops/sec ±0.78% (90 runs sampled)
815 protobuf.js (static) x 290,096 ops/sec ±0.96% (90 runs sampled)
816 JSON (string) x 129,381 ops/sec ±0.77% (90 runs sampled)
817 JSON (buffer) x 91,051 ops/sec ±0.94% (90 runs sampled)
818 google-protobuf x 42,050 ops/sec ±0.85% (91 runs sampled)
820 protobuf.js (static) was fastest
821 protobuf.js (reflect) was 4.7% ops/sec slower (factor 1.0)
822 JSON (string) was 55.3% ops/sec slower (factor 2.2)
823 JSON (buffer) was 68.6% ops/sec slower (factor 3.2)
824 google-protobuf was 85.5% ops/sec slower (factor 6.9)
827 These results are achieved by
829 * generating type-specific encoders, decoders, verifiers and converters at runtime
830 * configuring the reader/writer interface according to the environment
831 * using node-specific functionality where beneficial and, of course
832 * avoiding unnecessary operations through splitting up [the toolset](#toolset).
834 You can also run [the benchmark](https://github.com/dcodeIO/protobuf.js/blob/master/bench/index.js) ...
840 and [the profiler](https://github.com/dcodeIO/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node):
843 $> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000]
846 Note that as of this writing, the benchmark suite performs significantly slower on node 7.2.0 compared to 6.9.1 because moths.
851 * Works in all modern and not-so-modern browsers except IE8.
852 * Because the internals of this package do not rely on `google/protobuf/descriptor.proto`, options are parsed and presented literally.
853 * If typed arrays are not supported by the environment, plain arrays will be used instead.
854 * 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).
855 * 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.
856 * 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)).
857 * For descriptor.proto interoperability, see [ext/descriptor](https://github.com/dcodeIO/protobuf.js/tree/master/ext/descriptor)
862 To build the library or its components yourself, clone it from GitHub and install the development dependencies:
865 $> git clone https://github.com/dcodeIO/protobuf.js.git
870 Building the respective development and production versions with their respective source maps to `dist/`:
876 Building the documentation to `docs/`:
882 Building the TypeScript definition to `index.d.ts`:
888 ### Browserify integration
890 By default, protobuf.js integrates into any browserify build-process without requiring any optional modules. Hence:
892 * 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.
894 If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically:
899 protobuf.util.Long = Long;
900 protobuf.configure();
903 * If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) for reference.
905 **License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)