Permalink
Browse files

Docs: Reference Buffer for BufferReader/Writer, see #668

  • Loading branch information...
dcodeIO committed Jan 30, 2017
1 parent 6a0920b commit c365242bdc28a47f5c6ab91bae34c277d1044eb3
Showing with 99 additions and 30 deletions.
  1. +31 −17 README.md
  2. +6 −4 cli/pbts.js
  3. +35 −5 index.d.ts
  4. +2 −2 src/reader.js
  5. +13 −0 src/reader_buffer.js
  6. +12 −2 src/writer_buffer.js
@@ -72,14 +72,18 @@ The library supports both reflection-based and code-based use cases:
There is a suitable distribution for each of these:
| Build | GZ Size | Downloads | How to require | Description
| | Gzipped | 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. No reflection.
In case of doubt you can just use the full library.
[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist
[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light
[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal
Examples
--------
@@ -302,7 +306,7 @@ protobuf.load("awesome.proto", function(err, root) {
});
```
To achieve the same with static code generated by [pbjs](https://github.com/dcodeIO/protobuf.js#command-line), there is the [pbts](https://github.com/dcodeIO/protobuf.js#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well.
To achieve the same with static code generated by [pbjs](#command-line), there is the [pbts](#generating-typescript-definitions-from-static-modules) command line utility to generate type definitions from static code as well.
Let's say you generated your static code to `bundle.js` and its type definitions to `bundle.d.ts`, then you can do:
@@ -358,13 +362,15 @@ Consolidates imports and converts between file formats.
default Default wrapper supporting both CommonJS and AMD
commonjs CommonJS wrapper
amd AMD wrapper
es6 ES6 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
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:
@@ -410,7 +416,7 @@ As you might have noticed, `pbjs` is also capable of generating static code. For
$> 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`, which then can be used with just the [minimal library][dist-minimal].
will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`, which then can be used with just the [minimal library](#distributions).
**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code.
@@ -421,16 +427,18 @@ Likewise, the `pbts` command line utility can be used to generate TypeScript def
```
Generates TypeScript definitions from annotated JavaScript files.
-n, --name Wraps everything in a module of the specified name.
-o, --out Saves to a file instead of writing to stdout.
-m, --main Whether building the main library without any imports.
-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] -
```
@@ -455,9 +463,9 @@ $> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts -
### On reflection vs. static code
While using .proto files directly requires the [full library][dist-full] respectively pure reflection/JSON the [light library][dist-light], pretty much all code but the relatively short descriptors is shared.
While using .proto files directly requires the [full library](#distributions) respectively pure reflection/JSON the [light library](#distributions), pretty much all code but the relatively short descriptors is shared.
Static code, on the other hand, requires just the [minimal library][dist-minimal], but generates additional, albeit editable, source code without any reflection features.
Static code, on the other hand, requires just the [minimal library](#distributions), 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.
@@ -590,11 +598,17 @@ $> npm run types
By default, protobuf.js integrates into your browserify build-process without requiring any optional modules. Hence:
* If you need int64 support, explicitly require the `long` module somewhere in your project. It will be excluded otherwise.
* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) as a reference.
* If you need int64 support, explicitly require the `long` module somewhere in your project as it will be excluded otherwise. This assumes that a global `require` function is present that protobuf.js can call to obtain the long module.
**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically:
[dist-full]: https://github.com/dcodeIO/protobuf.js/tree/master/dist
[dist-light]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/light
[dist-minimal]: https://github.com/dcodeIO/protobuf.js/tree/master/dist/minimal
```js
var Long = ...;
protobuf.util.Long = Long;
protobuf.configure();
```
* If you have any special requirements, there is [the bundler](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/bundle.js) for reference.
**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)
@@ -45,16 +45,18 @@ exports.main = function(args, callback) {
"",
chalk.bold.white("Generates TypeScript definitions from annotated JavaScript files."),
"",
" -n, --name Wraps everything in a module of the specified name.",
"",
" -o, --out Saves to a file instead of writing to stdout.",
"",
" -m, --main Whether building the main library without any imports.",
"",
" -g, --global Name of the global object in browser environments, if any.",
"",
" --no-comments Does not output any JSDoc comments.",
"",
chalk.bold.gray(" Internal flags:"),
"",
" -n, --name Wraps everything in a module of the specified name.",
"",
" -m, --main Whether building the main library without any imports.",
"",
"usage: " + chalk.bold.green("pbts") + " [options] file1.js file2.js ..." + chalk.bold.gray(" (or) ") + "other | " + chalk.bold.green("pbts") + " [options] -"
].join("\n"));
if (callback)
@@ -1174,10 +1174,10 @@ export class Reader {
/**
* Creates a new reader using the specified buffer.
* @function
* @param {Uint8Array} buffer Buffer to read from
* @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
* @param {Uint8Array|Buffer} buffer Buffer to read from
* @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
*/
static create(buffer: Uint8Array): (BufferReader|Reader);
static create(buffer: (Uint8Array|Buffer)): (Reader|BufferReader);
/**
* Reads a varint as an unsigned 32 bit value.
@@ -1314,6 +1314,21 @@ export class BufferReader extends Reader {
* @param {Buffer} buffer Buffer to read from
*/
constructor(buffer: Buffer);
/**
* Read buffer.
* @name BufferReader#buf
* @type {Buffer}
*/
buf: Buffer;
/**
* Reads a sequence of bytes preceeded by its length as a varint.
* @name BufferReader#bytes
* @function
* @returns {Buffer} Value read
*/
bytes(): Buffer;
}
/**
@@ -2703,9 +2718,24 @@ export class BufferWriter extends Writer {
/**
* Allocates a buffer of the specified size.
* @param {number} size Buffer size
* @returns {Uint8Array} Buffer
* @returns {Buffer} Buffer
*/
static alloc(size: number): Uint8Array;
static alloc(size: number): Buffer;
/**
* Writes a sequence of bytes.
* @param {Buffer|string} value Buffer or base64 encoded string to write
* @returns {Writer} `this`
*/
bytes(value: (Buffer|string)): Writer;
/**
* Finishes the write operation.
* @name BufferWriter#finish
* @function
* @returns {Buffer} Finished buffer
*/
finish(): Buffer;
}
/**
@@ -43,8 +43,8 @@ function Reader(buffer) {
/**
* Creates a new reader using the specified buffer.
* @function
* @param {Uint8Array} buffer Buffer to read from
* @returns {BufferReader|Reader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
* @param {Uint8Array|Buffer} buffer Buffer to read from
* @returns {Reader|BufferReader} A {@link BufferReader} if `buffer` is a Buffer, otherwise a {@link Reader}
*/
Reader.create = util.Buffer
? function create_buffer_setup(buffer) {
@@ -16,6 +16,12 @@ var util = require("./util/minimal");
*/
function BufferReader(buffer) {
Reader.call(this, buffer);
/**
* Read buffer.
* @name BufferReader#buf
* @type {Buffer}
*/
}
/* istanbul ignore else */
@@ -29,3 +35,10 @@ BufferReader.prototype.string = function read_string_buffer() {
var len = this.uint32(); // modifies pos
return this.buf.utf8Slice(this.pos, this.pos = Math.min(this.pos + len, this.len));
};
/**
* Reads a sequence of bytes preceeded by its length as a varint.
* @name BufferReader#bytes
* @function
* @returns {Buffer} Value read
*/
@@ -22,7 +22,7 @@ function BufferWriter() {
/**
* Allocates a buffer of the specified size.
* @param {number} size Buffer size
* @returns {Uint8Array} Buffer
* @returns {Buffer} Buffer
*/
BufferWriter.alloc = function alloc_buffer(size) {
return (BufferWriter.alloc = util._Buffer_allocUnsafe)(size);
@@ -42,7 +42,9 @@ var writeBytesBuffer = Buffer && Buffer.prototype instanceof Uint8Array && Buffe
};
/**
* @override
* Writes a sequence of bytes.
* @param {Buffer|string} value Buffer or base64 encoded string to write
* @returns {Writer} `this`
*/
BufferWriter.prototype.bytes = function write_bytes_buffer(value) {
if (util.isString(value))
@@ -71,3 +73,11 @@ BufferWriter.prototype.string = function write_string_buffer(value) {
this.push(writeStringBuffer, len, value);
return this;
};
/**
* Finishes the write operation.
* @name BufferWriter#finish
* @function
* @returns {Buffer} Finished buffer
*/

0 comments on commit c365242

Please sign in to comment.