Skip to content

Commit

Permalink
README on minimal runtime / available downloads [ci skip]
Browse files Browse the repository at this point in the history
  • Loading branch information
dcodeIO committed Dec 13, 2016
1 parent a54fbc9 commit ed86f3a
Show file tree
Hide file tree
Showing 4 changed files with 34 additions and 30 deletions.
54 changes: 28 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,10 +77,12 @@ Production:
<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.1.0/dist/protobuf.min.js"></script>
```

The `protobuf` namespace will be available globally.

**NOTE:** Remember to replace the version tag with the exact [release](https://github.com/dcodeIO/protobuf.js/releases) your project depends upon.

Or [download](https://github.com/dcodeIO/protobuf.js/tree/master/dist) the library.

The `protobuf` namespace will always be available globally but also supports AMD.

Examples
--------

Expand Down Expand Up @@ -336,14 +338,6 @@ protobuf.load("bundle.json", function(err, root) {
});
```

### Descriptors vs. static modules

While .proto and JSON files require the full library (about 20kb gzipped), pretty much all code but the relatively short descriptors is shared.

Static code, on the other hand, requires just the runtime library (about 5kb gzipped), but generates relatively large code bases without any reflection features.

When `new Function` is supported (and it usually is), there is no difference performance-wise as the code generated statically is the same generated at runtime.

### Generating TypeScript definitions from static modules

Likewise, the `pbts` command line utility can be used to generate TypeScript definitions from `pbjs`-generated static modules.
Expand All @@ -358,6 +352,14 @@ Generates TypeScript definitions from annotated JavaScript files.
usage: pbts [options] file1.js file2.js ...
```

### Descriptors vs. static modules

While .proto and JSON files require the full library (about 18kb gzipped), pretty much all code but the relatively short descriptors is shared.

Static code, on the other hand, requires just the minimal runtime (about 5.5kb gzipped), but generates relatively large code bases without any reflection features.

When `new Function` is supported (and it usually is), there is no difference performance-wise as the code generated statically is the same generated at runtime.

Building
--------

Expand Down Expand Up @@ -404,37 +406,37 @@ The package includes a benchmark that tries to compare performance to native JSO
```
benchmarking encoding performance ...
Type.encode to buffer x 479,876 ops/sec ±0.64% (92 runs sampled)
JSON.stringify to string x 311,489 ops/sec ±0.84% (87 runs sampled)
JSON.stringify to buffer x 175,079 ops/sec ±1.48% (82 runs sampled)
Type.encode to buffer x 481,172 ops/sec ±0.48% (92 runs sampled)
JSON.stringify to string x 307,509 ops/sec ±1.04% (92 runs sampled)
JSON.stringify to buffer x 164,463 ops/sec ±1.37% (89 runs sampled)
Type.encode to buffer was fastest
JSON.stringify to string was 35.2% slower
JSON.stringify to buffer was 63.8% slower
JSON.stringify to string was 36.4% slower
JSON.stringify to buffer was 66.1% slower
benchmarking decoding performance ...
Type.decode from buffer x 1,267,612 ops/sec ±1.18% (90 runs sampled)
JSON.parse from string x 291,707 ops/sec ±1.12% (92 runs sampled)
JSON.parse from buffer x 262,640 ops/sec ±0.77% (89 runs sampled)
Type.decode from buffer x 1,319,810 ops/sec ±0.71% (92 runs sampled)
JSON.parse from string x 298,578 ops/sec ±0.98% (90 runs sampled)
JSON.parse from buffer x 267,471 ops/sec ±0.81% (89 runs sampled)
Type.decode from buffer was fastest
JSON.parse from string was 77.0% slower
JSON.parse from buffer was 79.2% slower
JSON.parse from string was 77.4% slower
JSON.parse from buffer was 79.8% slower
benchmarking combined performance ...
Type to/from buffer x 248,897 ops/sec ±0.89% (90 runs sampled)
JSON to/from string x 126,848 ops/sec ±0.75% (92 runs sampled)
JSON to/from buffer x 89,854 ops/sec ±0.79% (93 runs sampled)
Type to/from buffer x 262,728 ops/sec ±0.92% (92 runs sampled)
JSON to/from string x 129,405 ops/sec ±0.78% (94 runs sampled)
JSON to/from buffer x 89,523 ops/sec ±0.71% (89 runs sampled)
Type to/from buffer was fastest
JSON to/from string was 49.0% slower
JSON to/from buffer was 63.9% slower
JSON to/from string was 50.7% slower
JSON to/from buffer was 65.9% slower
benchmarking verifying performance ...
Type.verify x 5,941,014 ops/sec ±0.96% (90 runs sampled)
Type.verify x 5,833,382 ops/sec ±0.98% (85 runs sampled)
Type.verify was fastest
```
Expand Down
2 changes: 2 additions & 0 deletions dist/README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
This folder contains prebuilt browser versions of [protobuf.js](https://github.com/dcodeIO/protobuf.js). When sending pull requests, it is not required to update these.

Alternatively, you can also use [the minimal runtime](./runtime) when working with statically generated code from `pbjs` *only*.

Prebuilt files are in source control to enable pain-free frontend respectively CDN usage:

CDN usage
Expand Down
4 changes: 2 additions & 2 deletions dist/runtime/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
This folder contains prebuilt browser versions of [protobuf.js](https://github.com/dcodeIO/protobuf.js)'s runtime for statically generated code. When sending pull requests, it is not required to update these.
This folder contains prebuilt browser versions of [protobuf.js](https://github.com/dcodeIO/protobuf.js)'s minimal runtime for statically generated code. When sending pull requests, it is not required to update these.

**NOTE:** The static code runtime includes just the bare minimum required to work with statically generated modules - and *nothing else*. Where applicable, it can be used as a drop-in replacement for the full library as it has the same general structure.
**NOTE:** The minimal runtime includes just the bare minimum required to work with statically generated code - and *nothing else*. Where applicable, it can be used as a drop-in replacement for the full library as it has the same general structure.

Prebuilt files are in source control to enable pain-free frontend respectively CDN usage:

Expand Down
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "protobufjs",
"version": "6.1.0",
"description": "Protocol Buffers for JavaScript.",
"version": "6.1.1",
"description": "Protocol Buffers for JavaScript (& TypeScript).",
"author": "Daniel Wirtz <[email protected]>",
"license": "Apache-2.0",
"repository": {
Expand Down

0 comments on commit ed86f3a

Please sign in to comment.