Permalink
Browse files

Docs: Added extended usage instructions for TypeScript and custom cla…

…sses to README, see #666
  • Loading branch information...
dcodeIO committed Jan 28, 2017
1 parent 579068a commit fdc3102689e8a3e8345eee5ead07ba3c9c3fe80c
Showing with 76 additions and 14 deletions.
  1. +39 −4 README.md
  2. +37 −10 src/util/minimal.js
@@ -150,11 +150,19 @@ var root = new Root().define("awesomepackage").add(AwesomeMessage);
```js
...
// define your own prototypical class
function AwesomeMessage(properties) {
protobuf.Message.call(this, properties);
protobuf.Message.call(this, properties); // call the super constructor
}
// register your custom class with its reflected type
protobuf.Class.create(root.lookup("awesomepackage.AwesomeMessage") /* or use reflection */, AwesomeMessage);
// define your custom functionality
AwesomeMessage.customStaticMethod = function() { ... };
AwesomeMessage.prototype.customInstanceMethod = function() { ... };
// create a message
var message = new AwesomeMessage({ awesomeField: "AwesomeString" });
// Continue at "Encode a message" above
@@ -212,15 +220,42 @@ There is also an [example for streaming RPC](https://github.com/dcodeIO/protobuf
### Usage with TypeScript
The library ships with its own [type definitions](https://github.com/dcodeIO/protobuf.js/blob/master/index.d.ts) and modern editors like [Visual Studio Code](https://code.visualstudio.com/) should automatically detect and use them for code completion when following this pattern:
```ts
// node.js
import * as protobuf from "protobufjs";
import * as Long from "long"; // optional
...
// browser only (alternatively)
import * as protobuf from "./node_modules/protobufjs/index.js";
import * as Long from "./node_modules/long/dist/long.js"; // optional
protobuf.load("awesome.proto", function(err, root) {
if (err)
throw err;
// example code
var AwesomeMessage = root.lookupType("AwesomeMessage");
var message = AwesomeMessage.create({ awesomeField: "hello" });
var buffer = AwesomeMessage.encode(message).finish();
...
});
```
See also: [Generating your own TypeScript definitions](https://github.com/dcodeIO/protobuf.js#generating-typescript-definitions-from-static-modules)
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.
Let's say you generated your static code to `bundle.js` and its type definitions to `bundle.d.ts`, then you can do:
```ts
import * as root from "./bundle.js";
Additional configuration might be necessary when not utilizing node, i.e. reference [protobuf.js.d.ts](https://github.com/dcodeIO/protobuf.js/blob/master/index.d.ts) and [long.js.d.ts](https://github.com/DefinitelyTyped/DefinitelyTyped/blob/types-2.0/long/index.d.ts).
// example code
var AwesomeMessage = root.AwesomeMessage;
var message = AwesomeMessage.create({ awesomeField: "hello" });
var buffer = AwesomeMessage.encode(message).finish();
...
```
Documentation
-------------
@@ -1,27 +1,39 @@
"use strict";
var util = exports;
util.asPromise = require("@protobufjs/aspromise");
util.base64 = require("@protobufjs/base64");
// used to return a Promise where callback is omitted
util.asPromise = require("@protobufjs/aspromise");
// converts to / from base64 encoded strings
util.base64 = require("@protobufjs/base64");
// base class of rpc.Service
util.EventEmitter = require("@protobufjs/eventemitter");
util.inquire = require("@protobufjs/inquire");
util.utf8 = require("@protobufjs/utf8");
util.pool = require("@protobufjs/pool");
util.LongBits = require("./longbits");
// requires modules optionally and hides the call from bundlers
util.inquire = require("@protobufjs/inquire");
// convert to / from utf8 encoded strings
util.utf8 = require("@protobufjs/utf8");
// provides a node-like buffer pool in the browser
util.pool = require("@protobufjs/pool");
// utility to work with the low and high bits of a 64 bit value
util.LongBits = require("./longbits");
/**
* An immuable empty array.
* @memberof util
* @type {Array.<*>}
*/
util.emptyArray = Object.freeze ? Object.freeze([]) : /* istanbul ignore next */ [];
util.emptyArray = Object.freeze ? Object.freeze([]) : /* istanbul ignore next */ []; // used on prototypes
/**
* An immutable empty object.
* @type {Object}
*/
util.emptyObject = Object.freeze ? Object.freeze({}) : /* istanbul ignore next */ {};
util.emptyObject = Object.freeze ? Object.freeze({}) : /* istanbul ignore next */ {}; // used on prototypes
/**
* Whether running within node or not.
@@ -73,8 +85,23 @@ util.Buffer = (function() {
}
})();
// Aliases where supported, otherwise polyfills
/**
* Internal alias of or polyfull for Buffer.from.
* @type {?function}
* @param {string|number[]} value Value
* @param {string} [encoding] Encoding if value is a string
* @returns {Uint8Array}
* @private
*/
util._Buffer_from = null;
/**
* Internal alias of or polyfill for Buffer.allocUnsafe.
* @type {?function}
* @param {number} size Buffer size
* @returns {Uint8Array}
* @private
*/
util._Buffer_allocUnsafe = null;
/**
@@ -230,7 +257,7 @@ util._configure = function() {
util._Buffer_from = util._Buffer_allocUnsafe = null;
return;
}
// node 4.2.0 - 4.4.7 support makes it impossible to just polyfill these.
// because node 4.x buffers are incompatible & immutable
// see: https://github.com/dcodeIO/protobuf.js/pull/665
util._Buffer_from = Buffer.from !== Uint8Array.from && Buffer.from ||
/* istanbul ignore next */

0 comments on commit fdc3102

Please sign in to comment.