Breaking: Initial implementation of TypeScript decorators; Breaking: …

…Refactored protobuf.Class away; Breaking: TypeScript definitions now have (a lot of) generics; Breaking: Removed deprecated features; Other: tsd-jsdoc now has limited generics support

CHANGELOG.md

@@ -1,3 +1,8 @@
+# [6.7.3](https://github.com/dcodeIO/protobuf.js/releases/tag/6.7.3)
+
+## Other
+[:hash:](https://github.com/dcodeIO/protobuf.js/commit/57f1da64945f2dc5537c6eaa53e08e8fdd477b67) long, @types/long and @types/node are just dependencies, see [#753](https://github.com/dcodeIO/protobuf.js/issues/753)<br />
+
 # [6.7.2](https://github.com/dcodeIO/protobuf.js/releases/tag/6.7.2)
 
 ## New

README.md

@@ -249,7 +249,7 @@ protobuf.load("awesome.proto", function(err, root) {
         throw Error(errMsg);
 
     // Create a new message
-    var message = AwesomeMessage.creeate(payload); // or use .fromObject if conversion is necessary
+    var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary
 
     // Encode a message to an Uint8Array (browser) or Buffer (node)
     var buffer = AwesomeMessage.encode(message).finish();
@@ -518,6 +518,53 @@ If you are not building for node and/or not using long.js and want to exclude th
 /// <reference path="./node_modules/protobufjs/stub-node.d.ts" />
 ```
 
+#### Experimental decorators
+
+**WARNING:** Just introduced, not well tested, probably buggy.
+
+protobuf.js ships with an initial implementation of decorators, but note that decorators in TypeScript are an experimental feature and are subject to change without notice - plus - you have to enable the feature explicitly with the `experimentalDecorators` option:
+
+```ts
+import { Message, Type, Field, OneOf } from "protobufjs/light";
+
+@Type.d()
+export class AwesomeArrayMessage extends Message<AwesomeArrayMessage> {
+
+  @Field.d(1, "uint32", "repeated")
+  public awesomeArray: number[];
+
+}
+
+@Type.d()
+export class AwesomeStringMessage extends Message<AwesomeStringMessage> {
+
+  @Field.d(1, "string")
+  public awesomeString: string;
+
+}
+
+@Type.d()
+export class AwesomeMessage extends Message<AwesomeMessage> {
+
+  @Field.d(1, "string", "optional", "awesome default string")
+  public awesomeField: string;
+
+  @Field.d(2, AwesomeArrayMessage)
+  public awesomeArrayMessage: AwesomeArrayMessage;
+
+  @Field.d(3, AwesomeStringMessage)
+  public awesomeStringMessage: AwesomeStringMessage;
+
+  @OneOf.d("awesomeArrayMessage", "awesomeStringMessage")
+  public whichAwesomeMessage: string;
+
+}
+
+let awesomeMessage = new AwesomeMessage({ awesomeField: "hi" });
+let awesomeBuffer  = AwesomeMessage.encode(awesomeMessage).finish();
+let awesomeDecoded = AwesomeMessage.decode(awesomeBuffer);
+```
+
 Command line
 ------------
 

cli/lib/tsd-jsdoc.json

@@ -7,6 +7,9 @@
         "includePattern": ".+\\.js(doc)?$",
         "excludePattern": "(^|\\/|\\\\)_"
     },
+    "plugins": [
+        "./tsd-jsdoc/plugin"
+    ],
     "opts": {
         "encoding"      : "utf8",
         "recurse"       : true,

cli/lib/tsd-jsdoc/plugin.js

@@ -0,0 +1,21 @@
+"use strict";
+exports.defineTags = function(dictionary) {
+
+    dictionary.defineTag("template", {
+        mustHaveValue: true,
+        canHaveType: false,
+        canHaveName: false,
+        onTagged: function(doclet, tag) {
+            (doclet.templates || (doclet.templates = [])).push(tag.text);
+        }
+    });
+
+    dictionary.defineTag("tstype", {
+        mustHaveValue: true,
+        canHaveType: false,
+        canHaveName: false,
+        onTagged: function(doclet, tag) {
+            doclet.tsType = tag.text;
+        }
+    });
+};

cli/lib/tsd-jsdoc/publish.js

@@ -195,6 +195,8 @@ function getChildrenOf(parent) {
 
 // gets the literal type of an element
 function getTypeOf(element) {
+    if (element.tsType)
+        return element.tsType;
     var name = "any";
     var type = element.type;
     if (type && type.names && type.names.length) {
@@ -211,9 +213,9 @@ function getTypeOf(element) {
     // Ensure upper case Object for map expressions below
     name = name.replace(/\bobject\b/g, "Object");
 
-    // Correct Promise.<Something> to Promise<Something>
-    name = replaceRecursive(name, /\bPromise\.<([^>]*)>/gi, function($0, $1) {
-        return "Promise<" + $1 + ">";
+    // Correct Something.<Something> to Something<Something>
+    name = replaceRecursive(name, /\b(?!Object|Array)([\w$]+)\.<([^>]*)>/gi, function($0, $1, $2) {
+        return $1 + "<" + $2 + ">";
     });
 
     // Replace Array.<string> with string[]
@@ -226,8 +228,8 @@ function getTypeOf(element) {
         return "{ [k: " + $1 + "]: " + $2 + " }";
     });
 
-    // Replace functions (there are no signatures) with () => any
-    name = name.replace(/\bfunction(?:\(\))?([^\w]|$)/gi, "() => any");
+    // Replace functions (there are no signatures) with Function
+    name = name.replace(/\bfunction(?:\(\))?([^\w]|$)/g, "Function");
 
     // Convert plain Object back to just object
     if (name === "Object")
@@ -402,7 +404,10 @@ function handleClass(element, parent) {
             write("abstract ");
         write("class ");
     }
-    write(element.name, " ");
+    write(element.name);
+    if (element.templates && element.templates.length)
+        write("<", element.templates.join(", "), ">");
+    write(" ");
 
     // extended classes
     if (element.augments) {
@@ -520,6 +525,8 @@ function handleFunction(element, parent, isConstructor) {
         } else
             write("function ");
         write(element.name);
+        if (element.templates && element.templates.length)
+            write("<", element.templates.join(", "), ">");
     }
     writeFunctionSignature(element, isConstructor, false);
     writeln(";");
@@ -538,7 +545,10 @@ function handleTypeDef(element, parent) {
         // see: https://github.com/dcodeIO/protobuf.js/issues/737
         // begin(element, true);
         writeln();
-        write("type ", element.name, " = ");
+        write("type ", element.name);
+        if (element.templates && element.templates.length)
+            write("<", element.templates.join(", "), ">");
+        write(" = ");
         var type = getTypeOf(element);
         if (element.type && element.type.names.length === 1 && element.type.names[0] === "function")
             writeFunctionSignature(element, false, true);

cli/targets/static.js

@@ -520,16 +520,6 @@ function buildType(ref, type) {
         ]);
         buildFunction(type, "fromObject", protobuf.converter.fromObject(type));
 
-        push("");
-        pushComment([
-            "Creates " + aOrAn(type.name) + " message from a plain object. Also converts values to their respective internal types.",
-            "This is an alias of {@link " + fullName + ".fromObject}.",
-            "@function",
-            "@param {Object.<string,*>} object Plain object",
-            "@returns {" + fullName + "} " + type.name
-        ]);
-        push(name(type.name) + ".from = " + name(type.name) + ".fromObject;");
-
         push("");
         pushComment([
             "Creates a plain object from " + aOrAn(type.name) + " message. Also converts values to other types if specified.",

config/jsdoc.json

@@ -1,6 +1,6 @@
 {
     "tags": {
-        "allowUnknownTags": false
+        "allowUnknownTags": true
     },
     "source": {
         "include": [