From e64cf65b09047755899ec2330ca0fc2f4d7932c2 Mon Sep 17 00:00:00 2001 From: dcodeIO Date: Mon, 30 Jan 2017 02:46:41 +0100 Subject: [PATCH] Docs: Additional notes on the distinction of different use cases / distributions, see #666 --- README.md | 65 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 40 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 21d67af01..1cfd1565c 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,9 @@ Contents * [Usage](#usage)
How to include protobuf.js in your project. +* [Distributions](#distributions)
+ A brief introduction to the available distributions and their use cases. + * [Examples](#examples)
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