You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**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/)).
10
+
**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://protobuf.dev/)).
5
11
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!
12
+
**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, does not sacrifice on performance, has good conformance and works out of the box with [.proto](https://protobuf.dev/programming-guides/proto3/) files!
**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).
62
-
63
-
### Browsers
64
67
65
-
Development:
68
+
The optional [command line utility](./cli/) to generate static code and reflection bundles lives in the `protobufjs-cli` package and can be installed separately:
Pick the variant matching your needs and replace the version tag with the exact [release](https://github.com/protobufjs/protobuf.js/tags) your project depends upon. For example, to use the minified full variant:
**Remember** to replace the version tag with the exact [release](https://github.com/protobufjs/protobuf.js/tags) your project depends upon.
78
-
79
-
The library supports CommonJS and AMD loaders and also exports globally as `protobuf`.
80
-
81
-
### Distributions
82
-
83
-
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:
84
-
85
-
* When working with JSON descriptors (i.e. generated by [pbjs](cli/README.md#pbjs-for-javascript)) and/or reflection only, see the [light library][dist-light] (~16kb gzipped) that excludes the parser. CommonJS entry point is:
86
-
87
-
```js
88
-
var protobuf =require("protobufjs/light");
89
-
```
90
-
91
-
* When working with statically generated code only, see the [minimal library][dist-minimal] (~6.5kb gzipped) that also excludes reflection. CommonJS entry point is:
92
-
93
-
```js
94
-
var protobuf =require("protobufjs/minimal");
95
-
```
96
-
97
82
| Distribution | Location
98
-
|------------|-----------------------------------
99
-
| Full | <https://cdn.jsdelivr.net/npm/protobufjs/dist/>
All variants support CommonJS and AMD loaders and export globally as `window.protobuf`.
102
89
103
90
Usage
104
91
-----
105
92
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):
93
+
Because JavaScript is a dynamically typed language, protobuf.js utilizes the concept of a **valid message** in order to provide the best possible [performance](#performance) (and, as a side product, proper typings):
107
94
108
95
### Valid message
109
96
110
97
> 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
98
112
99
There are two possible types of valid messages and the encoder is able to work with both of these for convenience:
113
100
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
101
+
***Message instances** (explicit instances of message classes with default values on their prototype) naturally satisfy the requirements of a valid message and
115
102
***Plain JavaScript objects** that just so happen to be composed in a way satisfying the requirements of a valid message as well.
116
103
117
104
In a nutshell, the wire format writer understands the following types:
@@ -126,11 +113,11 @@ In a nutshell, the wire format writer understands the following types:
126
113
| 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
114
| enum | `number` (32 bit integer) | Looks up the numeric id if a `string`
* 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.
120
+
* Maps are objects where the key is the string representation of the respective value or an 8 characters long hash string for `Long`-likes.
134
121
135
122
### Toolset
136
123
@@ -210,7 +197,7 @@ For reference, the following diagram aims to display relationships between the d
> 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))
200
+
> 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/protobufjs/protobuf.js/issues/748#issuecomment-291925749))
There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf.js/blob/master/examples/streaming-rpc.js).
472
+
There is also an [example for streaming RPC](https://github.com/protobufjs/protobuf.js/blob/master/examples/streaming-rpc.js).
486
473
487
474
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.
488
475
489
476
### Usage with TypeScript
490
477
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.
478
+
The library ships with its own [type definitions](https://github.com/protobufjs/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.
492
479
493
480
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.
494
481
@@ -595,18 +582,18 @@ Other notes:
595
582
* Default values must be specified as arguments to the decorator instead of using a property initializer for proper prototype behavior.
596
583
* 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.
597
584
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.
585
+
**ProTip!** Not as pretty, but you can [use decorators in plain JavaScript](https://github.com/protobufjs/protobuf.js/blob/master/examples/js-decorators.js) as well.
*[Frequently asked questions](https://github.com/protobufjs/protobuf.js/wiki) on our wiki
610
597
611
598
#### Community
612
599
*[Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow
@@ -666,13 +653,13 @@ These results are achieved by
666
653
* using node-specific functionality where beneficial and, of course
667
654
* avoiding unnecessary operations through splitting up [the toolset](#toolset).
668
655
669
-
You can also run [the benchmark](https://github.com/dcodeIO/protobuf.js/blob/master/bench/index.js) ...
656
+
You can also run [the benchmark](https://github.com/protobufjs/protobuf.js/blob/master/bench/index.js) ...
670
657
671
658
```
672
659
$> npm run bench
673
660
```
674
661
675
-
and [the profiler](https://github.com/dcodeIO/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node):
662
+
and [the profiler](https://github.com/protobufjs/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node):
676
663
677
664
```
678
665
$> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000]
@@ -686,18 +673,18 @@ Compatibility
686
673
* Works in all modern and not-so-modern browsers except IE8.
687
674
* Because the internals of this package do not rely on `google/protobuf/descriptor.proto`, options are parsed and presented literally.
688
675
* If typed arrays are not supported by the environment, plain arrays will be used instead.
689
-
* 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).
690
-
* 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.
676
+
* Support for pre-ES5 environments (except IE8) can be achieved by [using a polyfill](https://github.com/protobufjs/protobuf.js/blob/master/lib/polyfill.js).
677
+
* Support for [Content Security Policy](https://w3c.github.io/webappsec-csp/)-restricted environments (like Chrome extensions without unsafe-eval) can be achieved by generating and using static code instead.
691
678
* 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)).
692
-
* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/dcodeIO/protobuf.js/tree/master/ext/descriptor)
679
+
* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/protobufjs/protobuf.js/tree/master/ext/descriptor)
693
680
694
681
Building
695
682
--------
696
683
697
684
To build the library or its components yourself, clone it from GitHub and install the development dependencies:
0 commit comments