From 412407de9afb7ec3a999c4c9a3a1f388f971fce7 Mon Sep 17 00:00:00 2001 From: dcodeIO Date: Tue, 4 Apr 2017 13:42:19 +0200 Subject: [PATCH] Docs: Restructured README --- README.md | 186 +++++++++++++++++++++++++++++++++++++++++++++++--- cli/README.md | 185 +------------------------------------------------ 2 files changed, 177 insertions(+), 194 deletions(-) diff --git a/README.md b/README.md index 6f784f0cd..e822e7e9f 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,24 @@ Contents * [Examples](#examples)
A few examples to get you started. -* [Documentation](#documentation)
- A list of available documentation resources. + * [Using .proto files](#using-proto-files) + * [Using JSON descriptors](#using-json-descriptors) + * [Using reflection only](#using-reflection-only) + * [Using custom classes](#using-custom-classes) + * [Using services](#using-services) + * [Usage with TypeScript](#usage-with-typescript) * [Command line](#command-line)
How to use the command line utility. + * [pbjs for JavaScript](#pbjs-for-javascript) + * [pbts for TypeScript](#pbts-for-typescript) + * [Reflection vs. static code](#reflection-vs-static-code) + * [Command line API](#command-line-api) + +* [Additional documentation](#additional-documentation)
+ A list of available documentation resources. + * [Performance](#performance)
A few internals and a benchmark on performance. @@ -329,7 +341,7 @@ var root = new Root().define("awesomepackage").add(AwesomeMessage); ... ``` -Detailed information on the reflection structure is available within the [documentation](#documentation). +Detailed information on the reflection structure is available within the [API documentation](#additional-documentation). ### Using custom classes @@ -465,7 +477,7 @@ protobuf.load("awesome.proto", function(err, root) { }); ``` -**Note:** Dynamically generated runtime message classes cannot be typed, technically, so you must either access its fields using `message["awesomeField"]` notation or you can utilize [typings of its static counterpart](https://github.com/dcodeIO/protobuf.js/tree/master/cli#pbts) for full typings support. +**Note:** Dynamically generated runtime message classes cannot be typed, technically, so you must either access its fields using `message["awesomeField"]` notation or you can utilize [typings of its static counterpart](#pbts-for-typescript) for full typings support. If you generated static code to `bundle.js` using the CLI and its type definitions to `bundle.d.ts` instead, then you can just do: @@ -486,25 +498,177 @@ var buffer = AwesomeMessage.encode(message).finish(); /// ``` -Documentation -------------- +Command line +------------ + +**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. + +The command line interface (CLI) can be used to translate between file formats and to generate static code as well as TypeScript definitions. + +### pbjs for JavaScript + +``` +Translates between file formats and generates static code. + + -t, --target Specifies the target format. Also accepts a path to require a custom target. + + json JSON representation + json-module JSON representation as a module + proto2 Protocol Buffers, Version 2 + proto3 Protocol Buffers, Version 3 + static Static code without reflection (non-functional on its own) + static-module Static code without reflection as a module + + -p, --path Adds a directory to the include path. + + -o, --out Saves to a file instead of writing to stdout. + + --sparse Exports only those types referenced from a main file (experimental). + + Module targets only: + + -w, --wrap Specifies the wrapper to use. Also accepts a path to require a custom wrapper. + + default Default wrapper supporting both CommonJS and AMD + commonjs CommonJS wrapper + amd AMD wrapper + es6 ES6 wrapper (implies --es6) + + -r, --root Specifies an alternative protobuf.roots name. + + -l, --lint Linter configuration. Defaults to protobuf.js-compatible rules: + + eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins + + --es6 Enables ES6 syntax (const/let instead of var) + + Proto sources only: + + --keep-case Keeps field casing instead of converting to camel case. + + Static targets only: + + --no-create Does not generate create functions used for reflection compatibility. + --no-encode Does not generate encode functions. + --no-decode Does not generate decode functions. + --no-verify Does not generate verify functions. + --no-convert Does not generate convert functions like from/toObject + --no-delimited Does not generate delimited encode/decode functions. + --no-beautify Does not beautify generated code. + --no-comments Does not output any JSDoc comments. + + --force-long Enfores the use of 'Long' for s-/u-/int64 and s-/fixed64 fields. + --force-message Enfores the use of runtime messages instead of plain objects. + +usage: pbjs [options] file1.proto file2.json ... (or) other | pbjs [options] - +``` + +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): + +``` +$> pbjs -t json file1.proto file2.proto > bundle.json +``` + +Now, either include this file in your final bundle: + +```js +var root = protobuf.Root.fromJSON(require("./bundle.json")); +``` + +or load it the usual way: + +```js +protobuf.load("bundle.json", function(err, root) { + ... +}); +``` + +Generated static code, on the other hand, works with just the **minimal** library. For example + +``` +$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto +``` + +will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`. + +**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code. + + +### pbts for TypeScript + +``` +Generates TypeScript definitions from annotated JavaScript files. + + -o, --out Saves to a file instead of writing to stdout. + + -g, --global Name of the global object in browser environments, if any. + + --no-comments Does not output any JSDoc comments. + + Internal flags: + + -n, --name Wraps everything in a module of the specified name. + + -m, --main Whether building the main library without any imports. + +usage: pbts [options] file1.js file2.js ... (or) other | pbts [options] - +``` + +Picking up on the example above, the following not just generates static code to a CommonJS module `compiled.js` but also its respective TypeScript definitions to `compiled.d.ts`: + +``` +$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto +$> pbts -o compiled.d.ts compiled.js +``` + +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: + +1. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor. +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")`). + +For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code: + +``` +$> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto +$> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts - +``` + +### Reflection vs. static code + +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. + +Static code, on the other hand, requires just the minimal library, but generates additional, albeit editable, source code without any reflection features. + +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. + +### Command line API + +Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions: + +```js +var pbjs = require("protobufjs/cli/pbjs"); // or require("protobufjs/cli").pbjs / .pbts + +pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) { + if (err) + throw err; + // do something with output +}); +``` + +Additional documentation +------------------------ #### Protocol Buffers * [Google's Developer Guide](https://developers.google.com/protocol-buffers/docs/overview) #### protobuf.js * [API Documentation](http://dcode.io/protobuf.js) -* [CLI Documentation](./cli/README.md) * [CHANGELOG](https://github.com/dcodeIO/protobuf.js/blob/master/CHANGELOG.md) * [Frequently asked questions](https://github.com/dcodeIO/protobuf.js/wiki) on our wiki #### Community * [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow -Command line ------------- -Command line usage has moved to the (soon to be decoupled) [CLI package](./cli/README.md) - Performance ----------- The package includes a benchmark that tries to compare performance to native JSON as far as this is possible. On an i7-2600K running node 6.9.1 it yields: diff --git a/cli/README.md b/cli/README.md index e3b252232..1eb4c868a 100644 --- a/cli/README.md +++ b/cli/README.md @@ -4,189 +4,8 @@ protobufjs-cli Command line interface (CLI) for [protobuf.js](https://github.com/dcodeIO/protobuf.js). Translates between file formats and generates static code as well as TypeScript definitions. -**Note** that moving the CLI to its own package is a work in progress. At the moment, it's still part of the main package. - -Contents --------- - - - -* [Usage](#usage)
- An introduction to the toolset. - -* [API](#api)
- Details on using pbjs and pbts programmatically. - - - -Usage ------ - -### pbjs - -``` -Translates between file formats and generates static code. - - -t, --target Specifies the target format. Also accepts a path to require a custom target. - - json JSON representation - json-module JSON representation as a module - proto2 Protocol Buffers, Version 2 - proto3 Protocol Buffers, Version 3 - static Static code without reflection (non-functional on its own) - static-module Static code without reflection as a module - - -p, --path Adds a directory to the include path. - - -o, --out Saves to a file instead of writing to stdout. - - --sparse Exports only those types referenced from a main file (experimental). - - Module targets only: - - -w, --wrap Specifies the wrapper to use. Also accepts a path to require a custom wrapper. - - default Default wrapper supporting both CommonJS and AMD - commonjs CommonJS wrapper - amd AMD wrapper - es6 ES6 wrapper (implies --es6) - - -r, --root Specifies an alternative protobuf.roots name. - - -l, --lint Linter configuration. Defaults to protobuf.js-compatible rules: - - eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins - - --es6 Enables ES6 syntax (const/let instead of var) - - Proto sources only: - - --keep-case Keeps field casing instead of converting to camel case. - - Static targets only: - - --no-create Does not generate create functions used for reflection compatibility. - --no-encode Does not generate encode functions. - --no-decode Does not generate decode functions. - --no-verify Does not generate verify functions. - --no-convert Does not generate convert functions like from/toObject - --no-delimited Does not generate delimited encode/decode functions. - --no-beautify Does not beautify generated code. - --no-comments Does not output any JSDoc comments. - - --force-long Enfores the use of 'Long' for s-/u-/int64 and s-/fixed64 fields. - --force-message Enfores the use of runtime messages instead of plain objects. - -usage: pbjs [options] file1.proto file2.json ... (or) other | pbjs [options] - -``` - -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): +* [CLI Documentation](https://github.com/dcodeIO/protobuf.js#command-line) -``` -$> pbjs -t json file1.proto file2.proto > bundle.json -``` - -Now, either include this file in your final bundle: - -```js -var root = protobuf.Root.fromJSON(require("./bundle.json")); -``` - -or load it the usual way: - -```js -protobuf.load("bundle.json", function(err, root) { - ... -}); -``` - -Generated static code, on the other hand, works with just the **minimal** library. For example - -``` -$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto -``` - -will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`. - -**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code. - - -### pbts - -``` -Generates TypeScript definitions from annotated JavaScript files. - - -o, --out Saves to a file instead of writing to stdout. - - -g, --global Name of the global object in browser environments, if any. - - --no-comments Does not output any JSDoc comments. - - Internal flags: - - -n, --name Wraps everything in a module of the specified name. - - -m, --main Whether building the main library without any imports. - -usage: pbts [options] file1.js file2.js ... (or) other | pbts [options] - -``` - -Picking up on the example above, the following not just generates static code to a CommonJS module `compiled.js` but also its respective TypeScript definitions to `compiled.d.ts`: - -``` -$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto -$> pbts -o compiled.d.ts compiled.js -``` - -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: - -1. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor. -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")`). - -For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code: - -``` -$> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto -$> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts - -``` - -### Reflection vs. static code - -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. - -Static code, on the other hand, requires just the minimal library, but generates additional, albeit editable, source code without any reflection features. - -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. - -API ---- - -Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions: - -```js -var pbjs = require("protobufjs-cli/pbjs"); // or require("protobufjs-cli").pbjs / .pbts - -pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) { - if (err) - throw err; - // do something with output -}); -``` +**Note** that moving the CLI to its own package is a work in progress. At the moment, it's still part of the main package. **License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)