Permalink
Browse files

Docs: Additional notes on the distinction of different use cases / di…

…stributions, see #666
  • Loading branch information...
dcodeIO committed Jan 30, 2017
1 parent 83758c9 commit e64cf65b09047755899ec2330ca0fc2f4d7932c2
Showing with 40 additions and 25 deletions.
  1. +40 −25 README.md
@@ -22,6 +22,9 @@ Contents
* [Usage](#usage)<br />
How to include protobuf.js in your project.
* [Distributions](#distributions)<br />
A brief introduction to the available distributions and their use cases.
* [Examples](#examples)<br />
A few examples to get you started.
@@ -69,20 +72,31 @@ Production:
The `protobuf` namespace will always be available globally / also supports AMD loaders.
Additionally, the library is compiled in different versions. Which one to use depends on whether bundle size is a factor and your use case:
Distributions
-------------
The library supports both reflection-based and code-based use cases:
1. Parsing protocol buffer definitions (.proto files) to reflection
2. Loading JSON descriptors to reflection
3. Generating static code without any reflection features
| Build | Downloads | How to require | Description
|---------|------------------------------|---------------------------------|-------------
| full | [dist][dist-full] | `require("protobufjs")` | All features. Works with everything.
| light | [dist/light][dist-light] | `require("protobufjs/light")` | All features except tokenizer, parser and bundled common types. Works with reflection, JSON definitions and static code.
| minimal | [dist/minimal][dist-minimal] | `require("protobufjs/minimal")` | Just enough to run statically generated code. Works with static code only.
There is a suitable distribution for each of these:
| Build | GZ Size | Downloads | How to require | Description
|---------|---------|------------------------------|---------------------------------|-------------
| full | 18.5kb | [dist][dist-full] | `require("protobufjs")` | All features. Works with everything.
| light | 15.5kb | [dist/light][dist-light] | `require("protobufjs/light")` | All features except tokenizer, parser and bundled common types. Works with JSON definitions, pure reflection and static code.
| minimal | 6.0kb+ | [dist/minimal][dist-minimal] | `require("protobufjs/minimal")` | Just enough to run static code - and nothing else.
In case of doubt you can just use the full library.
Examples
--------
### Using .proto files
It's super easy to load an existing .proto file using the full build, which parses and compiles the definitions to ready to use runtime message classes:
It's possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use runtime message classes:
```protobuf
// awesome.proto
@@ -131,7 +145,9 @@ protobuf.load("awesome.proto")
### Using JSON descriptors
The library utilizes a JSON format that is equivalent to a .proto definition (see also: [Command line usage](#command-line)). The following is identical to the .proto definition seen above:
The library utilizes a JSON format that is equivalent to a .proto definition (see also: [Command line usage](#command-line)).
The following is identical to the .proto definition seen above, but it can also be used with just the light library because it doesn't require the parser:
```json
// awesome.json
@@ -162,15 +178,16 @@ protobuf.load("awesome.json", function(err, root) {
Or you can load it inline:
```js
var root = protobuf.Root.fromJSON(descriptorJson);
var jsonDescriptor = require("./awesome.json"); // exemplary for node
var root = protobuf.Root.fromJSON(jsonDescriptor);
// Continue at "Obtain a message type" above
```
### Using reflection only
Both the full and the light build include full reflection support. You could, for example, define the .proto definitions seen in the example above using just reflection:
Both the full and the light library include full reflection support. You could, for example, define the .proto definitions seen in the examples above using just reflection:
```js
...
@@ -218,11 +235,20 @@ AwesomeMessage.prototype.customInstanceMethod = function() { ... };
* `AwesomeMessage.verify`
* `AwesomeMessage.fromObject`, `AwesomeMessage.toObject`, `AwesomeMessage#toObject` and `AwesomeMessage#toJSON`
### Using the Reader/Writer interface directly
### Using services
While only useful for the adventurous cherishing an aversion to [generated static code](https://github.com/dcodeIO/protobuf.js#command-line), it's also possible to use the Reader/Writer interface directly depending just on the [minimal library][dist-minimal] ([basic example](https://github.com/dcodeIO/protobuf.js/blob/master/examples/reader-writer.js)). Easy ways to obtain example code snippets are either setting `protobuf.util.codegen.verbose = true` while watching the console as code generation happens, or simply inspecting generated static code.
The library also supports 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 HelloRequest and a node-style callback as its parameters:
### Using services
```js
function rpcImpl(method, requestData, callback) {
// perform the request using an HTTP request or a WebSocket for example
var responseData = ...;
// and call the callback with the binary response afterwards:
callback(null, responseData);
}
```
Example:
```protobuf
// greeter.proto
@@ -260,17 +286,6 @@ greeter.sayHello({ name: 'you' })
});
```
To make this work, all you have to do is provide an `rpcImpl`, which is an asynchronous function that takes the reflected service method, the binary HelloRequest and a node-style callback as its parameters. For example:
```js
function rpcImpl(method, requestData, callback) {
// perform the request using an HTTP request or a WebSocket for example
var responseData = ...;
// and call the callback with the binary response afterwards:
callback(null, responseData);
}
```
There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf.js/blob/master/examples/streaming-rpc.js).
### Usage with TypeScript

0 comments on commit e64cf65

Please sign in to comment.