Skip to content

Commit a75625d

Browse files
dcodeIOdcodeIO
committed
CLI: Decoupled message properties as an interface in static code for TS intellisense support, see #717 
1 parent 23f14a6 commit a75625d

10 files changed

Lines changed: 1659 additions & 1967 deletions

File tree

‎cli/targets/static.js‎

Lines changed: 24 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -284,34 +284,41 @@ function toJsType(field) {
284284
function buildType(ref, type) {
285285
var fullName = type.fullName.substring(1);
286286

287+
if (config.comments) {
288+
var typeDef = [
289+
"Properties of " + aOrAn(type.name) + ".",
290+
"@typedef " + fullName + "$Properties",
291+
"@type Object"
292+
];
293+
type.fieldsArray.forEach(function(field) {
294+
var jsType = toJsType(field);
295+
if (field.map)
296+
jsType = "Object.<string," + jsType + ">";
297+
else if (field.repeated)
298+
jsType = "Array.<" + jsType + ">";
299+
typeDef.push("@property {" + jsType + "} " + (field.optional ? "[" + field.name + "]" : field.name) + " " + (field.comment || type.name + " " + field.name + "."));
300+
});
301+
push("");
302+
pushComment(typeDef);
303+
}
304+
287305
push("");
288306
pushComment([
289307
"Constructs a new " + type.name + ".",
290308
type.comment ? "@classdesc " + type.comment : null,
291309
"@exports " + fullName,
310+
"@implements " + fullName + "$Properties",
292311
"@constructor",
293-
"@param {Object.<string,*>=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
312+
"@param {" + fullName + "$Properties=} [" + (config.beautify ? "properties" : "p") + "] Properties to set"
294313
]);
295314
buildFunction(type, type.name, Class.generate(type));
296315

297316
// default values
298317
var firstField = true;
299318
type.fieldsArray.forEach(function(field) {
300319
field.resolve();
301-
var jsType = toJsType(field);
302-
if (field.map)
303-
jsType = "Object.<string," + jsType + ">"; // keys are always strings
304-
else if (field.repeated)
305-
jsType = "Array.<" + jsType + ">";
306320
var prop = util.safeProp(field.name);
307-
if (config.comments) {
308-
push("");
309-
pushComment([
310-
field.comment || type.name + " " + field.name + ".",
311-
prop.charAt(0) !== "." ? "@name " + fullName + "#" + field.name : null,
312-
"@type {" + jsType + (field.optional ? "|undefined": "") + "}"
313-
]);
314-
} else if (firstField) {
321+
if (firstField) {
315322
push("");
316323
firstField = false;
317324
}
@@ -360,7 +367,7 @@ function buildType(ref, type) {
360367
push("");
361368
pushComment([
362369
"Creates a new " + type.name + " instance using the specified properties.",
363-
"@param {Object.<string,*>=} [properties] Properties to set",
370+
"@param {" + fullName + "$Properties=} [properties] Properties to set",
364371
"@returns {" + fullName + "} " + type.name + " instance"
365372
]);
366373
push(name(type.name) + ".create = function create(properties) {");
@@ -374,7 +381,7 @@ function buildType(ref, type) {
374381
push("");
375382
pushComment([
376383
"Encodes the specified " + type.name + " message. Does not implicitly {@link " + fullName + ".verify|verify} messages.",
377-
"@param {" + fullName + "|Object.<string,*>} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
384+
"@param {" + fullName + "$Properties} " + (config.beautify ? "message" : "m") + " " + type.name + " message or plain object to encode",
378385
"@param {$protobuf.Writer} [" + (config.beautify ? "writer" : "w") + "] Writer to encode to",
379386
"@returns {$protobuf.Writer} Writer"
380387
]);
@@ -436,7 +443,7 @@ function buildType(ref, type) {
436443
push("");
437444
pushComment([
438445
"Verifies " + aOrAn(type.name) + " message.",
439-
"@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " " + type.name + " object to verify",
446+
"@param {Object.<string,*>} " + (config.beautify ? "message" : "m") + " Plain object to verify",
440447
"@returns {?string} `null` if valid, otherwise the reason why it is not"
441448
]);
442449
buildFunction(type, "verify", protobuf.verifier(type));

‎index.d.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ export class Class {
3333
* @param {Type} type Reflected message type
3434
* @param {*} [ctor] Custom constructor to set up, defaults to create a generic one if omitted
3535
* @returns {Message} Message prototype
36-
* @deprecated Assign the constructor to {@link Type#ctor} instead
36+
* @deprecated since 6.7.0 it's possible to just assign a new constructor to {@link Type#ctor}
3737
*/
3838
public static create(type: Type, ctor?: any): Message;
3939

@@ -2332,6 +2332,7 @@ export namespace util {
23322332
* @param {Root} root Root instanceof
23332333
* @param {Object.<number,string|ReflectionObject>} lazyTypes Type names
23342334
* @returns {undefined}
2335+
* @deprecated since 6.7.0 static code does not emit lazy types anymore
23352336
*/
23362337
function lazyResolve(root: Root, lazyTypes: { [k: number]: (string|ReflectionObject) }): void;
23372338

‎tests/data/comments.js‎

Lines changed: 25 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -11,43 +11,39 @@ var $root = $protobuf.roots.test_comments || ($protobuf.roots.test_comments = {}
1111

1212
$root.Test1 = (function() {
1313

14+
/**
15+
* Properties of a Test1.
16+
* @typedef Test1$Properties
17+
* @type Object
18+
* @property {string} [field1] Field with a comment.
19+
* @property {number} [field2] Test1 field2.
20+
* @property {boolean} [field3] Field with a comment and a <a href="http://example.com/foo/">link</a>
21+
*/
22+
1423
/**
1524
* Constructs a new Test1.
1625
* @classdesc Message
1726
* with
1827
* a
1928
* comment.
2029
* @exports Test1
30+
* @implements Test1$Properties
2131
* @constructor
22-
* @param {Object.<string,*>=} [properties] Properties to set
32+
* @param {Test1$Properties=} [properties] Properties to set
2333
*/
2434
function Test1(properties) {
2535
if (properties)
2636
for (var keys = Object.keys(properties), i = 0; i < keys.length; ++i)
2737
this[keys[i]] = properties[keys[i]];
2838
}
2939

30-
/**
31-
* Field with a comment.
32-
* @type {string|undefined}
33-
*/
3440
Test1.prototype.field1 = "";
35-
36-
/**
37-
* Test1 field2.
38-
* @type {number|undefined}
39-
*/
4041
Test1.prototype.field2 = 0;
41-
42-
/**
43-
* Field with a comment and a <a href="http://example.com/foo/">link</a>
44-
* @type {boolean|undefined}
45-
*/
4642
Test1.prototype.field3 = false;
4743

4844
/**
4945
* Creates a new Test1 instance using the specified properties.
50-
* @param {Object.<string,*>=} [properties] Properties to set
46+
* @param {Test1$Properties=} [properties] Properties to set
5147
* @returns {Test1} Test1 instance
5248
*/
5349
Test1.create = function create(properties) {
@@ -56,7 +52,7 @@ $root.Test1 = (function() {
5652

5753
/**
5854
* Encodes the specified Test1 message. Does not implicitly {@link Test1.verify|verify} messages.
59-
* @param {Test1|Object.<string,*>} message Test1 message or plain object to encode
55+
* @param {Test1$Properties} message Test1 message or plain object to encode
6056
* @param {$protobuf.Writer} [writer] Writer to encode to
6157
* @returns {$protobuf.Writer} Writer
6258
*/
@@ -129,7 +125,7 @@ $root.Test1 = (function() {
129125

130126
/**
131127
* Verifies a Test1 message.
132-
* @param {Object.<string,*>} message Test1 object to verify
128+
* @param {Object.<string,*>} message Plain object to verify
133129
* @returns {?string} `null` if valid, otherwise the reason why it is not
134130
*/
135131
Test1.verify = function verify(message) {
@@ -220,11 +216,18 @@ $root.Test1 = (function() {
220216

221217
$root.Test2 = (function() {
222218

219+
/**
220+
* Properties of a Test2.
221+
* @typedef Test2$Properties
222+
* @type Object
223+
*/
224+
223225
/**
224226
* Constructs a new Test2.
225227
* @exports Test2
228+
* @implements Test2$Properties
226229
* @constructor
227-
* @param {Object.<string,*>=} [properties] Properties to set
230+
* @param {Test2$Properties=} [properties] Properties to set
228231
*/
229232
function Test2(properties) {
230233
if (properties)
@@ -234,7 +237,7 @@ $root.Test2 = (function() {
234237

235238
/**
236239
* Creates a new Test2 instance using the specified properties.
237-
* @param {Object.<string,*>=} [properties] Properties to set
240+
* @param {Test2$Properties=} [properties] Properties to set
238241
* @returns {Test2} Test2 instance
239242
*/
240243
Test2.create = function create(properties) {
@@ -243,7 +246,7 @@ $root.Test2 = (function() {
243246

244247
/**
245248
* Encodes the specified Test2 message. Does not implicitly {@link Test2.verify|verify} messages.
246-
* @param {Test2|Object.<string,*>} message Test2 message or plain object to encode
249+
* @param {Test2$Properties} message Test2 message or plain object to encode
247250
* @param {$protobuf.Writer} [writer] Writer to encode to
248251
* @returns {$protobuf.Writer} Writer
249252
*/
@@ -301,7 +304,7 @@ $root.Test2 = (function() {
301304

302305
/**
303306
* Verifies a Test2 message.
304-
* @param {Object.<string,*>} message Test2 object to verify
307+
* @param {Object.<string,*>} message Plain object to verify
305308
* @returns {?string} `null` if valid, otherwise the reason why it is not
306309
*/
307310
Test2.verify = function verify(message) {

‎tests/data/convert.js‎

Lines changed: 20 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,27 @@ var $root = $protobuf.roots.test_convert || ($protobuf.roots.test_convert = {});
1111

1212
$root.Message = (function() {
1313

14+
/**
15+
* Properties of a Message.
16+
* @typedef Message$Properties
17+
* @type Object
18+
* @property {string} [stringVal] Message stringVal.
19+
* @property {Array.<string>} [stringRepeated] Message stringRepeated.
20+
* @property {number|$protobuf.Long} [uint64Val] Message uint64Val.
21+
* @property {Array.<number|$protobuf.Long>} [uint64Repeated] Message uint64Repeated.
22+
* @property {Uint8Array} [bytesVal] Message bytesVal.
23+
* @property {Array.<Uint8Array>} [bytesRepeated] Message bytesRepeated.
24+
* @property {number} [enumVal] Message enumVal.
25+
* @property {Array.<number>} [enumRepeated] Message enumRepeated.
26+
* @property {Object.<string,number|$protobuf.Long>} [int64Map] Message int64Map.
27+
*/
28+
1429
/**
1530
* Constructs a new Message.
1631
* @exports Message
32+
* @implements Message$Properties
1733
* @constructor
18-
* @param {Object.<string,*>=} [properties] Properties to set
34+
* @param {Message$Properties=} [properties] Properties to set
1935
*/
2036
function Message(properties) {
2137
this.stringRepeated = [];
@@ -28,63 +44,19 @@ $root.Message = (function() {
2844
this[keys[i]] = properties[keys[i]];
2945
}
3046

31-
/**
32-
* Message stringVal.
33-
* @type {string|undefined}
34-
*/
3547
Message.prototype.stringVal = "";
36-
37-
/**
38-
* Message stringRepeated.
39-
* @type {Array.<string>|undefined}
40-
*/
4148
Message.prototype.stringRepeated = $util.emptyArray;
42-
43-
/**
44-
* Message uint64Val.
45-
* @type {number|$protobuf.Long|undefined}
46-
*/
4749
Message.prototype.uint64Val = $util.Long ? $util.Long.fromBits(0,0,true) : 0;
48-
49-
/**
50-
* Message uint64Repeated.
51-
* @type {Array.<number|$protobuf.Long>|undefined}
52-
*/
5350
Message.prototype.uint64Repeated = $util.emptyArray;
54-
55-
/**
56-
* Message bytesVal.
57-
* @type {Uint8Array|undefined}
58-
*/
5951
Message.prototype.bytesVal = $util.newBuffer([]);
60-
61-
/**
62-
* Message bytesRepeated.
63-
* @type {Array.<Uint8Array>|undefined}
64-
*/
6552
Message.prototype.bytesRepeated = $util.emptyArray;
66-
67-
/**
68-
* Message enumVal.
69-
* @type {number|undefined}
70-
*/
7153
Message.prototype.enumVal = 1;
72-
73-
/**
74-
* Message enumRepeated.
75-
* @type {Array.<number>|undefined}
76-
*/
7754
Message.prototype.enumRepeated = $util.emptyArray;
78-
79-
/**
80-
* Message int64Map.
81-
* @type {Object.<string,number|$protobuf.Long>|undefined}
82-
*/
8355
Message.prototype.int64Map = $util.emptyObject;
8456

8557
/**
8658
* Creates a new Message instance using the specified properties.
87-
* @param {Object.<string,*>=} [properties] Properties to set
59+
* @param {Message$Properties=} [properties] Properties to set
8860
* @returns {Message} Message instance
8961
*/
9062
Message.create = function create(properties) {
@@ -93,7 +65,7 @@ $root.Message = (function() {
9365

9466
/**
9567
* Encodes the specified Message message. Does not implicitly {@link Message.verify|verify} messages.
96-
* @param {Message|Object.<string,*>} message Message message or plain object to encode
68+
* @param {Message$Properties} message Message message or plain object to encode
9769
* @param {$protobuf.Writer} [writer] Writer to encode to
9870
* @returns {$protobuf.Writer} Writer
9971
*/
@@ -230,7 +202,7 @@ $root.Message = (function() {
230202

231203
/**
232204
* Verifies a Message message.
233-
* @param {Object.<string,*>} message Message object to verify
205+
* @param {Object.<string,*>} message Plain object to verify
234206
* @returns {?string} `null` if valid, otherwise the reason why it is not
235207
*/
236208
Message.verify = function verify(message) {

0 commit comments

Comments
 (0)