Other: TypeScript generics improvements

Author: dcodeIO

README.md

@@ -543,34 +543,40 @@ export class AwesomeMessage extends Message<AwesomeMessage> {
   @Field.d(2, AwesomeSubMessage)
   public awesomeSubMessage: AwesomeSubMessage;
 
-  @Field.d(3, AwesomeEnum)
+  @Field.d(3, AwesomeEnum, "optional", AwesomeEnum.ONE)
   public awesomeEnum: AwesomeEnum;
 
   @OneOf.d("awesomeSubMessage", "awesomeEnum")
   public which: string;
 
 }
 
-let message = new AwesomeMessage({ awesomeField: "hi" });
+// example code
+let message = new AwesomeMessage({ awesomeField: "hello" });
 let buffer  = AwesomeMessage.encode(message).finish();
 let decoded = AwesomeMessage.decode(buffer);
 ```
 
 Supported decorators are:
 
-* **Type.d(typeName?: `string`)**<br />
-  optionally annotates a class as a protobuf message type. If `typeName` is not specified, the constructor's runtime function name is used.
+* **Type.d(typeName?: `string`)** &nbsp; *(optional)*<br />
+  annotates a class as a protobuf message type. If `typeName` is not specified, the constructor's runtime function name is used for the reflected type.
 
 * **Field.d&lt;T>(fieldId: `number`, fieldType: `string | TMessageConstructor<TField>`, fieldRule?: `"optional" | "required" | "repeated"`, defaultValue?: `T`)**<br />
   annotates a property as a protobuf field with the specified id and protobuf type.
 
-* **MapField.d&lt;T extends { [key: string]: any }>(fieldId: `number`, fieldKeyType: `string`, fieldValueType. `string | TConstructor<{}>`)**<br />
+* **MapField.d&lt;T extends { [key: string]: any }>(fieldId: `number`, fieldKeyType: `string`, fieldValueType. `string | Constructor<{}>`)**<br />
   annotates a property as a protobuf map field with the specified id, protobuf key and value type.
 
 * **OneOf.d&lt;T extends string>(...fieldNames: `string[]`)**<br />
   annotates a property as a protobuf oneof covering the specified fields.
 
-Decorated types reside in `protobuf.roots["decorators"]` using a flat structure (no duplicate names).
+Other notes:
+
+* Decorated types reside in `protobuf.roots["decorated"]` using a flat structure, so no duplicate names.
+* Enums are copied to a reflected enum with a generic name on decorator evaluation because referenced enum objects have no runtime name the decorator could use.
+* Default values must be specified as arguments to the decorator instead of using a property initializer for proper prototype behavior.
+* Property names on decorated classes must not be renamed on compile time (i.e. by a minifier) because decorators just receive the original field name as a string.
 
 Command line
 ------------

config/eslint.json

@@ -97,9 +97,10 @@
         "no-shadow-restricted-names": 1,
         "no-shadow": 0,                     // this is javascript. it has forEach and all that stuff.
         "no-undef-init": 1,
-        "no-undef": 1,
+        "no-undef": 2,
         "no-undefined": 0,                  // produces shorter code when testing against this
         "no-use-before-define": 0,          // can actually be used for a better overview, i.e. with module.exports
+        "no-unused-vars": 1,                // a warning is sufficient
 
         // Node.js and CommonJS
         "callback-return": 1,

index.d.ts

@@ -15,3 +15,18 @@ function inquire(moduleName) {
     } catch (e) {} // eslint-disable-line no-empty
     return null;
 }
+
+/*
+// maybe worth a shot to prevent renaming issues:
+// see: https://github.com/webpack/webpack/blob/master/lib/dependencies/CommonJsRequireDependencyParserPlugin.js
+// triggers on:
+// - expression require.cache
+// - expression require (???)
+// - call require
+// - call require:commonjs:item
+// - call require:commonjs:context
+
+Object.defineProperty(Function.prototype, "__self", { get: function() { return this; } });
+var r = require.__self;
+delete Function.prototype.__self;
+*/

lib/inquire/index.js

@@ -1,8 +1,6 @@
 "use strict";
 module.exports = common;
 
-var Type = require("./type");
-
 /**
  * Provides common type definitions.
  * Can also be used to provide additional google types or your own custom types.

src/common.js

@@ -327,7 +327,7 @@ Field.prototype.resolve = function resolve() {
  * @param {"optional"|"required"|"repeated"} [fieldRule="optional"] Field rule
  * @param {T} [defaultValue] Default value
  * @returns {FieldDecorator} Decorator function
- * @template T
+ * @template T extends number | number[] | Long | Long[] | string | string[] | boolean | boolean[] | Uint8Array | Uint8Array[] | Buffer | Buffer[]
  */
 Field.d = function decorateField(fieldId, fieldType, fieldRule, defaultValue) {
 
@@ -350,7 +350,7 @@ Field.d = function decorateField(fieldId, fieldType, fieldRule, defaultValue) {
  * @name Field.d
  * @function
  * @param {number} fieldId Field id
- * @param {TMessageConstructor<T>} fieldType Field type
+ * @param {Constructor<T>} fieldType Field type
  * @param {"optional"|"required"|"repeated"} [fieldRule="optional"] Field rule
  * @returns {FieldDecorator} Decorator function
  * @template T extends Message<T>

src/field.js

@@ -108,9 +108,9 @@ MapField.prototype.resolve = function resolve() {
  * @function
  * @param {number} fieldId Field id
  * @param {"int32"|"uint32"|"sint32"|"fixed32"|"sfixed32"|"int64"|"uint64"|"sint64"|"fixed64"|"sfixed64"|"bool"|"string"} fieldKeyType Field key type
- * @param {"double"|"float"|"int32"|"uint32"|"sint32"|"fixed32"|"sfixed32"|"int64"|"uint64"|"sint64"|"fixed64"|"sfixed64"|"bool"|"string"|"bytes"|Object|TConstructor<{}>} fieldValueType Field value type
+ * @param {"double"|"float"|"int32"|"uint32"|"sint32"|"fixed32"|"sfixed32"|"int64"|"uint64"|"sint64"|"fixed64"|"sfixed64"|"bool"|"string"|"bytes"|Object|Constructor<{}>} fieldValueType Field value type
  * @returns {FieldDecorator} Decorator function
- * @template T extends { [key: string]: any }
+ * @template T extends { [key: string]: number | Long | string | boolean | Uint8Array | Buffer | number[] | Message<{}> }
  */
 MapField.d = function decorateMapField(fieldId, fieldKeyType, fieldValueType) {
 

src/mapfield.js

@@ -3,19 +3,12 @@ module.exports = Message;
 
 var util = require("./util");
 
-/**
- * Properties of a message instance.
- * @typedef TMessageProperties
- * @template T
- * @tstype { [P in keyof T]?: T[P] }
- */
-
 /**
  * Constructs a new message instance.
  * @classdesc Abstract runtime message.
  * @constructor
- * @param {TMessageProperties<T>} [properties] Properties to set
- * @template T
+ * @param {Properties<T>} [properties] Properties to set
+ * @template T extends object
  */
 function Message(properties) {
     // not used internally
@@ -45,7 +38,7 @@ function Message(properties) {
  * @param {Object.<string,*>} [properties] Properties to set
  * @returns {Message<T>} Message instance
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.create = function create(properties) {
     return this.$type.create(properties);
@@ -57,7 +50,7 @@ Message.create = function create(properties) {
  * @param {Writer} [writer] Writer to use
  * @returns {Writer} Writer
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.encode = function encode(message, writer) {
     return this.$type.encode(message, writer);
@@ -69,7 +62,7 @@ Message.encode = function encode(message, writer) {
  * @param {Writer} [writer] Writer to use
  * @returns {Writer} Writer
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.encodeDelimited = function encodeDelimited(message, writer) {
     return this.$type.encodeDelimited(message, writer);
@@ -82,7 +75,7 @@ Message.encodeDelimited = function encodeDelimited(message, writer) {
  * @param {Reader|Uint8Array} reader Reader or buffer to decode
  * @returns {T} Decoded message
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.decode = function decode(reader) {
     return this.$type.decode(reader);
@@ -95,7 +88,7 @@ Message.decode = function decode(reader) {
  * @param {Reader|Uint8Array} reader Reader or buffer to decode
  * @returns {T} Decoded message
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.decodeDelimited = function decodeDelimited(reader) {
     return this.$type.decodeDelimited(reader);
@@ -117,7 +110,7 @@ Message.verify = function verify(message) {
  * @param {Object.<string,*>} object Plain object
  * @returns {T} Message instance
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.fromObject = function fromObject(object) {
     return this.$type.fromObject(object);
@@ -129,7 +122,7 @@ Message.fromObject = function fromObject(object) {
  * @param {ConversionOptions} [options] Conversion options
  * @returns {Object.<string,*>} Plain object
  * @template T extends Message<T>
- * @this TMessageConstructor<T>
+ * @this Constructor<T>
  */
 Message.toObject = function toObject(message, options) {
     return this.$type.toObject(message, options);

src/message.js

@@ -10,7 +10,7 @@ var rpc = exports;
  * RPC implementation passed to {@link Service#create} performing a service request on network level, i.e. by utilizing http requests or websockets.
  * @typedef RPCImpl
  * @type {function}
- * @param {Method|rpc.ServiceMethod<{},{}>} method Reflected or static method being called
+ * @param {Method|rpc.ServiceMethod<Message<{}>,Message<{}>>} method Reflected or static method being called
  * @param {Uint8Array} requestData Request data
  * @param {RPCImplCallback} callback Callback function
  * @returns {undefined}

src/rpc.js

@@ -11,7 +11,7 @@ var util = require("../util/minimal");
  *
  * Differs from {@link RPCImplCallback} in that it is an actual callback of a service method which may not return `response = null`.
  * @typedef rpc.ServiceMethodCallback
- * @template TRes
+ * @template TRes extends Message<TRes>
  * @type {function}
  * @param {?Error} error Error, if any
  * @param {?TRes} [response] Response message
@@ -21,10 +21,10 @@ var util = require("../util/minimal");
 /**
  * A service method part of a {@link rpc.Service} as created by {@link Service.create}.
  * @typedef rpc.ServiceMethod
- * @template TReq
- * @template TRes
+ * @template TReq extends Message<TReq>
+ * @template TRes extends Message<TRes>
  * @type {function}
- * @param {TReq|TMessageProperties<TReq>} request Request message or plain object
+ * @param {TReq|Properties<TReq>} request Request message or plain object
  * @param {rpc.ServiceMethodCallback<TRes>} [callback] Node-style callback called with the error, if any, and the response message
  * @returns {Promise<Message<TRes>>} Promise if `callback` has been omitted, otherwise `undefined`
  */
@@ -68,9 +68,9 @@ function Service(rpcImpl, requestDelimited, responseDelimited) {
 /**
  * Calls a service method through {@link rpc.Service#rpcImpl|rpcImpl}.
  * @param {Method|rpc.ServiceMethod<TReq,TRes>} method Reflected or static method
- * @param {TMessageConstructor<TReq>} requestCtor Request constructor
- * @param {TMessageConstructor<TRes>} responseCtor Response constructor
- * @param {TReq|TMessageProperties<TReq>} request Request message or plain object
+ * @param {Constructor<TReq>} requestCtor Request constructor
+ * @param {Constructor<TRes>} responseCtor Response constructor
+ * @param {TReq|Properties<TReq>} request Request message or plain object
  * @param {rpc.ServiceMethodCallback<TRes>} callback Service callback
  * @returns {undefined}
  * @template TReq extends Message<TReq>