175 lines
7.6 KiB
Markdown
175 lines
7.6 KiB
Markdown
protobufjs-cli
|
|
==============
|
|
[](https://www.npmjs.com/package/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.
|
|
|
|
* [CLI Documentation](https://github.com/dcodeIO/protobuf.js#command-line)
|
|
|
|
**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.
|
|
* [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)<br />
|
|
|
|
### 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)
|
|
closure A closure adding to protobuf.roots where protobuf is a global
|
|
|
|
-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.
|
|
--no-service Does not output service classes.
|
|
|
|
--force-long Enforces the use of 'Long' for s-/u-/int64 and s-/fixed64 fields.
|
|
--force-number Enforces the use of 'number' for s-/u-/int64 and s-/fixed64 fields.
|
|
--force-message Enforces the use of message instances instead of plain objects.
|
|
|
|
usage: pbjs [options] file1.proto file2.json ... (or pipe) 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 only 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 source code without any reflection features. This also implies that there is a break-even point where statically generated code becomes larger than descriptor-based code once the amount of code generated exceeds the size of the full respectively light library.
|
|
|
|
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.
|
|
|
|
| Source | Library | Advantages | Tradeoffs
|
|
|--------|---------|------------|-----------
|
|
| .proto | full | Easily editable<br />Interoperability with other libraries<br />No compile step | Some parsing and possibly network overhead
|
|
| JSON | light | Easily editable<br />No parsing overhead<br />Single bundle (no network overhead) | protobuf.js specific<br />Has a compile step
|
|
| static | minimal | Works where `eval` access is restricted<br />Fully documented<br />Small footprint for small protos | Can be hard to edit<br />No reflection<br />Has a compile step
|
|
|
|
### 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
|
|
});
|
|
```
|
|
|
|
**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
|