CLI: Decoupled message properties as an interface in static code for TS intellisense support, see #717

Author: dcodeIO

cli/targets/static.js

@@ -284,34 +284,41 @@ function toJsType(field) {
 function buildType(ref, type) {
     var fullName = type.fullName.substring(1);
 
+    if (config.comments) {
+        var typeDef = [
+            "Properties of " + aOrAn(type.name) + ".",
+            "@typedef " + fullName + "$Properties",
+            "@type Object"
+        ];
+        type.fieldsArray.forEach(function(field) {
+            var jsType = toJsType(field);
+            if (field.map)
+                jsType = "Object.<string," + jsType + ">";
+            else if (field.repeated)
+                jsType = "Array.<" + jsType + ">";
+            typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + field.name + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
+        });
+        push("");
+        pushComment(typeDef);
+    }
+
     push("");
     pushComment([
         "Constructs a new " + type.name + ".",
         type.comment ? "@classdesc " + type.comment : null,
         "@exports " + fullName,
+        "@implements " + fullName + "$Properties",
         "@constructor",
-        "@param {Object.<string,*>=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
+        "@param {" + fullName + "$Properties=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
     ]);
     buildFunction(type, type.name, Class.generate(type));
 
     // default values
     var firstField = true;
     type.fieldsArray.forEach(function(field) {
         field.resolve();
-        var jsType = toJsType(field);
-        if (field.map)
-            jsType = "Object.<string," + jsType + ">"; // keys are always strings
-        else if (field.repeated)
-            jsType = "Array.<" + jsType + ">";
         var prop = util.safeProp(field.name);
-        if (config.comments) {
-            push("");
-            pushComment([
-                field.comment || type.name + " " + field.name + ".",
-                prop.charAt(0) !== "." ? "@name " + fullName + "#" + field.name : null,
-                "@type {" + jsType + (field.optional ? "|undefined": "") + "}"
-            ]);
-        } else if (firstField) {
+        if (firstField) {
             push("");
             firstField = false;
         }
@@ -360,7 +367,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Creates a new " + type.name + " instance using the specified properties.",
-            "@param {Object.<string,*>=} [properties] Properties to set",
+            "@param {" + fullName + "$Properties=} [properties] Properties to set",
             "@returns {" + fullName + "} " + type.name + " instance"
         ]);
         push(name(type.name) + ".create = function create(properties) {");
@@ -374,7 +381,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Encodes the specified " + type.name + " message. Does not implicitly {@link " + fullName + ".verify|verify} messages.",
-            "@param {" + fullName + "|Object.<string,*>} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
+            "@param {" + fullName + "$Properties} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
             "@param {$protobuf.Writer} [" + (config.beautify ? "writer" : "w") + "] Writer to encode to",
             "@returns {$protobuf.Writer} Writer"
         ]);
@@ -436,7 +443,7 @@ function buildType(ref, type) {
         push("");
         pushComment([
             "Verifies " + aOrAn(type.name) + " message.",
-            "@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " " + type.name + " object to verify",
+            "@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
             "@returns {?string} `null` if valid, otherwise the reason why it is not"
         ]);
         buildFunction(type, "verify", protobuf.verifier(type));

index.d.ts

@@ -33,7 +33,7 @@ export class Class {
      * @param {Type} type Reflected message type
      * @param {*} [ctor] Custom constructor to set up, defaults to create a generic one if omitted
      * @returns {Message} Message prototype
-     * @deprecated Assign the constructor to {@link Type#ctor} instead
+     * @deprecated since 6.7.0 it's possible to just assign a new constructor to {@link Type#ctor}
      */
     public static create(type: Type, ctor?: any): Message;
 
@@ -2332,6 +2332,7 @@ export namespace util {
      * @param {Root} root Root instanceof
      * @param {Object.<number,string|ReflectionObject>} lazyTypes Type names
      * @returns {undefined}
+     * @deprecated since 6.7.0 static code does not emit lazy types anymore
      */
     function lazyResolve(root: Root, lazyTypes: { [k: number]: (string|ReflectionObject) }): void;
 

tests/data/comments.js

@@ -11,43 +11,39 @@ var $root = $protobuf.roots.test_comments || ($protobuf.roots.test_comments = {}
 
 $root.Test1 = (function() {
 
+    /**
+     * Properties of a Test1.
+     * @typedef Test1$Properties
+     * @type Object
+     * @property {string} [field1] Field with a comment.
+     * @property {number} [field2] Test1 field2.
+     * @property {boolean} [field3] Field with a comment and a <a href="http://example.com/foo/">link</a>
+     */
+
     /**
      * Constructs a new Test1.
      * @classdesc Message
      * with
      * a
      * comment.
      * @exports Test1
+     * @implements Test1$Properties
      * @constructor
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Test1$Properties=} [properties] Properties to set
      */
     function Test1(properties) {
         if (properties)
             for (var keys = Object.keys(properties), i = 0; i < keys.length; ++i)
                 this[keys[i]] = properties[keys[i]];
     }
 
-    /**
-     * Field with a comment.
-     * @type {string|undefined}
-     */
     Test1.prototype.field1 = "";
-
-    /**
-     * Test1 field2.
-     * @type {number|undefined}
-     */
     Test1.prototype.field2 = 0;
-
-    /**
-     * Field with a comment and a <a href="http://example.com/foo/">link</a>
-     * @type {boolean|undefined}
-     */
     Test1.prototype.field3 = false;
 
     /**
      * Creates a new Test1 instance using the specified properties.
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Test1$Properties=} [properties] Properties to set
      * @returns {Test1} Test1 instance
      */
     Test1.create = function create(properties) {
@@ -56,7 +52,7 @@ $root.Test1 = (function() {
 
     /**
      * Encodes the specified Test1 message. Does not implicitly {@link Test1.verify|verify} messages.
-     * @param {Test1|Object.<string,*>} message Test1 message or plain object to encode
+     * @param {Test1$Properties} message Test1 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
      */
@@ -129,7 +125,7 @@ $root.Test1 = (function() {
 
     /**
      * Verifies a Test1 message.
-     * @param {Object.<string,*>} message Test1 object to verify
+     * @param {Object.<string,*>} message Plain object to verify
      * @returns {?string} `null` if valid, otherwise the reason why it is not
      */
     Test1.verify = function verify(message) {
@@ -220,11 +216,18 @@ $root.Test1 = (function() {
 
 $root.Test2 = (function() {
 
+    /**
+     * Properties of a Test2.
+     * @typedef Test2$Properties
+     * @type Object
+     */
+
     /**
      * Constructs a new Test2.
      * @exports Test2
+     * @implements Test2$Properties
      * @constructor
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Test2$Properties=} [properties] Properties to set
      */
     function Test2(properties) {
         if (properties)
@@ -234,7 +237,7 @@ $root.Test2 = (function() {
 
     /**
      * Creates a new Test2 instance using the specified properties.
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Test2$Properties=} [properties] Properties to set
      * @returns {Test2} Test2 instance
      */
     Test2.create = function create(properties) {
@@ -243,7 +246,7 @@ $root.Test2 = (function() {
 
     /**
      * Encodes the specified Test2 message. Does not implicitly {@link Test2.verify|verify} messages.
-     * @param {Test2|Object.<string,*>} message Test2 message or plain object to encode
+     * @param {Test2$Properties} message Test2 message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
      */
@@ -301,7 +304,7 @@ $root.Test2 = (function() {
 
     /**
      * Verifies a Test2 message.
-     * @param {Object.<string,*>} message Test2 object to verify
+     * @param {Object.<string,*>} message Plain object to verify
      * @returns {?string} `null` if valid, otherwise the reason why it is not
      */
     Test2.verify = function verify(message) {

tests/data/convert.js

@@ -11,11 +11,27 @@ var $root = $protobuf.roots.test_convert || ($protobuf.roots.test_convert = {});
 
 $root.Message = (function() {
 
+    /**
+     * Properties of a Message.
+     * @typedef Message$Properties
+     * @type Object
+     * @property {string} [stringVal] Message stringVal.
+     * @property {Array.<string>} [stringRepeated] Message stringRepeated.
+     * @property {number|$protobuf.Long} [uint64Val] Message uint64Val.
+     * @property {Array.<number|$protobuf.Long>} [uint64Repeated] Message uint64Repeated.
+     * @property {Uint8Array} [bytesVal] Message bytesVal.
+     * @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
+     * @property {number} [enumVal] Message enumVal.
+     * @property {Array.<number>} [enumRepeated] Message enumRepeated.
+     * @property {Object.<string,number|$protobuf.Long>} [int64Map] Message int64Map.
+     */
+
     /**
      * Constructs a new Message.
      * @exports Message
+     * @implements Message$Properties
      * @constructor
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Message$Properties=} [properties] Properties to set
      */
     function Message(properties) {
         this.stringRepeated = [];
@@ -28,63 +44,19 @@ $root.Message = (function() {
                 this[keys[i]] = properties[keys[i]];
     }
 
-    /**
-     * Message stringVal.
-     * @type {string|undefined}
-     */
     Message.prototype.stringVal = "";
-
-    /**
-     * Message stringRepeated.
-     * @type {Array.<string>|undefined}
-     */
     Message.prototype.stringRepeated = $util.emptyArray;
-
-    /**
-     * Message uint64Val.
-     * @type {number|$protobuf.Long|undefined}
-     */
     Message.prototype.uint64Val = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
-
-    /**
-     * Message uint64Repeated.
-     * @type {Array.<number|$protobuf.Long>|undefined}
-     */
     Message.prototype.uint64Repeated = $util.emptyArray;
-
-    /**
-     * Message bytesVal.
-     * @type {Uint8Array|undefined}
-     */
     Message.prototype.bytesVal = $util.newBuffer([]);
-
-    /**
-     * Message bytesRepeated.
-     * @type {Array.<Uint8Array>|undefined}
-     */
     Message.prototype.bytesRepeated = $util.emptyArray;
-
-    /**
-     * Message enumVal.
-     * @type {number|undefined}
-     */
     Message.prototype.enumVal = 1;
-
-    /**
-     * Message enumRepeated.
-     * @type {Array.<number>|undefined}
-     */
     Message.prototype.enumRepeated = $util.emptyArray;
-
-    /**
-     * Message int64Map.
-     * @type {Object.<string,number|$protobuf.Long>|undefined}
-     */
     Message.prototype.int64Map = $util.emptyObject;
 
     /**
      * Creates a new Message instance using the specified properties.
-     * @param {Object.<string,*>=} [properties] Properties to set
+     * @param {Message$Properties=} [properties] Properties to set
      * @returns {Message} Message instance
      */
     Message.create = function create(properties) {
@@ -93,7 +65,7 @@ $root.Message = (function() {
 
     /**
      * Encodes the specified Message message. Does not implicitly {@link Message.verify|verify} messages.
-     * @param {Message|Object.<string,*>} message Message message or plain object to encode
+     * @param {Message$Properties} message Message message or plain object to encode
      * @param {$protobuf.Writer} [writer] Writer to encode to
      * @returns {$protobuf.Writer} Writer
      */
@@ -230,7 +202,7 @@ $root.Message = (function() {
 
     /**
      * Verifies a Message message.
-     * @param {Object.<string,*>} message Message object to verify
+     * @param {Object.<string,*>} message Plain object to verify
      * @returns {?string} `null` if valid, otherwise the reason why it is not
      */
     Message.verify = function verify(message) {