diff --git a/README.md b/README.md index 3a6d3ab4c..27d6aa6b4 100644 --- a/README.md +++ b/README.md @@ -465,12 +465,7 @@ Note that the service API is meant for clients. Implementing a server-side endpo 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/) will automatically detect and use them for code completion. -**Note** that the npm package depends on [@types/node](https://www.npmjs.com/package/@types/node) because of `Buffer` and [@types/long](https://www.npmjs.com/package/@types/long) because of `Long`. If you are not building for node and/or not using long.js and want to exclude their full type definitions manually for whatever reason, there are two stubs available that can be referenced instead of the respective full type definition: - -```ts -/// -/// -``` +The npm package depends on [@types/node](https://www.npmjs.com/package/@types/node) because of `Buffer` and [@types/long](https://www.npmjs.com/package/@types/long) because of `Long`. If you are not building for node and/or not using long.js, it should be safe to exclude them manually. #### Using the JS API diff --git a/cli/lib/tsd-jsdoc/publish.js b/cli/lib/tsd-jsdoc/publish.js index d21865a8d..3e783d991 100644 --- a/cli/lib/tsd-jsdoc/publish.js +++ b/cli/lib/tsd-jsdoc/publish.js @@ -134,7 +134,7 @@ function writeln() { indentWritten = false; } -var skipTagsRe = /@(type|memberof|name|exports|interface|extends|implements|constructor|function|template|property|this|typedef|variation|example|returns \{undefined})[^@$]*/g, +var skipTagsRe = /@(type|tstype|const|memberof|name|exports|interface|extends|implements|constructor|function|template|property|this|typedef|variation|example|returns \{undefined})[^@$]*/g, skipTypeRe = /(@[^ ]+) \{[^\s$]+}/g; // writes a comment @@ -468,7 +468,7 @@ function handleClass(element, parent) { // class-compatible members var incompatible = []; getChildrenOf(element).forEach(function(child) { - if (isClassLike(child) || element.kind === "module" || element.kind === "typedef") { + if (isClassLike(child) || child.kind === "module" || child.kind === "typedef" || child.isEnum) { incompatible.push(child); return; } @@ -515,7 +515,8 @@ function handleMember(element, parent) { } else { - if (isClassLike(parent)) { + var inClass = isClassLike(parent); + if (inClass) { write(element.access || "public", " "); if (element.scope === "static") write("static "); diff --git a/ext/descriptor/index.d.ts b/ext/descriptor/index.d.ts index fa2e4610b..6734fe98b 100644 --- a/ext/descriptor/index.d.ts +++ b/ext/descriptor/index.d.ts @@ -75,7 +75,7 @@ export interface IFieldDescriptorProto { defaultValue?: string; oneofIndex?: number; jsonName?: any; - options?: IFieldOptionsProperties; + options?: IFieldOptions; } type IFieldDescriptorProtoLabel = number; @@ -138,17 +138,9 @@ export const FileDescriptorSet: $protobuf.Type; export const FileDescriptorProto: $protobuf.Type; -export const DescriptorProto: $protobuf.Type; +export const DescriptorProto: $protobuf.Type & { ExtensionRange: $protobuf.Type, ReservedRange: $protobuf.Type }; -export const DescriptorProtoExtensionRange: $protobuf.Type; - -export const DescriptorProtoReservedRange: $protobuf.Type; - -export const FieldDescriptorProto: $protobuf.Type; - -export const FieldDescriptorProtoLabel: $protobuf.Enum; - -export const FieldDescriptorProtoType: $protobuf.Enum; +export const FieldDescriptorProto: $protobuf.Type & { Label: $protobuf.Enum, Type: $protobuf.Enum }; export const OneofDescriptorProto: $protobuf.Type; @@ -160,17 +152,11 @@ export const EnumValueDescriptorProto: $protobuf.Type; export const MethodDescriptorProto: $protobuf.Type; -export const FileOptions: $protobuf.Type; - -export const FileOptionsOptimizeMode: $protobuf.Enum; +export const FileOptions: $protobuf.Type & { OptimizeMode: $protobuf.Enum }; export const MessageOptions: $protobuf.Type; -export const FieldOptions: $protobuf.Type; - -export const FieldOptionsCType: $protobuf.Enum; - -export const FieldOptionsJSType: $protobuf.Enum; +export const FieldOptions: $protobuf.Type & { CType: $protobuf.Enum, JSType: $protobuf.Enum }; export const OneofOptions: $protobuf.Type; @@ -182,14 +168,8 @@ export const ServiceOptions: $protobuf.Type; export const MethodOptions: $protobuf.Type; -export const UninterpretedOption: $protobuf.Type; - -export const UninterpretedOptionNamePart: $protobuf.Type; - -export const SourceCodeInfo: $protobuf.Type; - -export const SourceCodeInfoLocation: $protobuf.Type; +export const UninterpretedOption: $protobuf.Type & { NamePart: $protobuf.Type }; -export const GeneratedCodeInfo: $protobuf.Type; +export const SourceCodeInfo: $protobuf.Type & { Location: $protobuf.Type }; -export const GeneratedCodeInfoAnnotation: $protobuf.Type; +export const GeneratedCodeInfo: $protobuf.Type & { Annotation: $protobuf.Type }; diff --git a/ext/descriptor/index.js b/ext/descriptor/index.js index fb597556e..664f96e68 100644 --- a/ext/descriptor/index.js +++ b/ext/descriptor/index.js @@ -313,7 +313,7 @@ Type.prototype.toDescriptor = function toDescriptor(syntax) { * @property {string} [defaultValue] Literal default value * @property {number} [oneofIndex] Oneof index if part of a oneof * @property {*} [jsonName] Not supported - * @property {IFieldOptionsProperties} [options] Field options + * @property {IFieldOptions} [options] Field options */ /** @@ -874,54 +874,28 @@ function underScore(str) { * Reflected descriptor proto. * @name DescriptorProto * @type {Type} + * @property {Type} ExtensionRange + * @property {Type} ReservedRange * @const - * @tstype $protobuf.Type - */ - -/** - * Reflected descriptor proto extension range. - * @name DescriptorProtoExtensionRange - * @type {Type} - * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * ExtensionRange: $protobuf.Type, + * ReservedRange: $protobuf.Type + * } */ -exports.DescriptorProtoExtensionRange = exports.DescriptorProto.ExtensionRange; - -/** - * Reflected descriptor proto reserved range. - * @name DescriptorProtoReservedRange - * @type {Type} - * @const - * @tstype $protobuf.Type - */ -exports.DescriptorProtoReservedRange = exports.DescriptorProto.ReservedRange; /** * Reflected field descriptor proto. * @name FieldDescriptorProto * @type {Type} + * @property {Enum} Label + * @property {Enum} Type * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * Label: $protobuf.Enum, + * Type: $protobuf.Enum + * } */ -/** - * Reflected field descriptor proto label. - * @name FieldDescriptorProtoLabel - * @type {Enum} - * @const - * @tstype $protobuf.Enum - */ -exports.FieldDescriptorProtoLabel = exports.FieldDescriptorProto.Label; - -/** - * Reflected field descriptor proto type. - * @name FieldDescriptorProtoType - * @type {Enum} - * @const - * @tstype $protobuf.Enum - */ -exports.FieldDescriptorProtoType = exports.FieldDescriptorProto.Type; - /** * Reflected oneof descriptor proto. * @name OneofDescriptorProto @@ -966,19 +940,13 @@ exports.FieldDescriptorProtoType = exports.FieldDescriptorProto.Type; * Reflected file options. * @name FileOptions * @type {Type} + * @property {Enum} OptimizeMode * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * OptimizeMode: $protobuf.Enum + * } */ -/** - * Reflected file options optimize mode. - * @name FileOptionsOptimizeMode - * @type {Type} - * @const - * @tstype $protobuf.Enum - */ -exports.FileOptionsOptimizeMode = exports.FileOptions.OptimizeMode; - /** * Reflected message options. * @name MessageOptions @@ -991,27 +959,14 @@ exports.FileOptionsOptimizeMode = exports.FileOptions.OptimizeMode; * Reflected field options. * @name FieldOptions * @type {Type} + * @property {Enum} CType + * @property {Enum} JSType * @const - * @tstype $protobuf.Type - */ - -/** - * Reflected field options c-type. - * @name FieldOptionsCType - * @type {Enum} - * @const - * @tstype $protobuf.Enum - */ -exports.FieldOptionsCType = exports.FieldOptions.CType; - -/** - * Reflected field options js-type. - * @name FieldOptionsJSType - * @type {Enum} - * @const - * @tstype $protobuf.Enum + * @tstype $protobuf.Type & { + * CType: $protobuf.Enum, + * JSType: $protobuf.Enum + * } */ -exports.FieldOptionsJSType = exports.FieldOptions.JSType; /** * Reflected oneof options. @@ -1057,49 +1012,31 @@ exports.FieldOptionsJSType = exports.FieldOptions.JSType; * Reflected uninterpretet option. * @name UninterpretedOption * @type {Type} + * @property {Type} NamePart * @const - * @tstype $protobuf.Type - */ - -/** - * Reflected uninterpreted option name part. - * @name UninterpretedOptionNamePart - * @type {Type} - * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * NamePart: $protobuf.Type + * } */ -exports.UninterpretedOptionNamePart = exports.UninterpretedOption.NamePart; /** * Reflected source code info. * @name SourceCodeInfo * @type {Type} + * @property {Type} Location * @const - * @tstype $protobuf.Type - */ - -/** - * Reflected source code info location. - * @name SourceCodeInfoLocation - * @type {Type} - * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * Location: $protobuf.Type + * } */ -exports.SourceCodeInfoLocation = exports.SourceCodeInfo.Location; /** * Reflected generated code info. * @name GeneratedCodeInfo * @type {Type} + * @property {Type} Annotation * @const - * @tstype $protobuf.Type - */ - -/** - * Reflected generated code info annotation. - * @name GeneratedCodeInfoAnnotation - * @type {Type} - * @const - * @tstype $protobuf.Type + * @tstype $protobuf.Type & { + * Annotation: $protobuf.Type + * } */ -exports.GeneratedCodeInfoAnnotation = exports.GeneratedCodeInfo.Annotation; diff --git a/index.d.ts b/index.d.ts index 38f43d32b..2b95a640a 100644 --- a/index.d.ts +++ b/index.d.ts @@ -428,10 +428,7 @@ export function load(filename: (string|string[]), root?: Root): Promise; */ export function loadSync(filename: (string|string[]), root?: Root): Root; -/** - * Build type, one of `"full"`, `"light"` or `"minimal"`. - * @const - */ +/** Build type, one of `"full"`, `"light"` or `"minimal"`. */ export const build: string; /** Reconfigures the library according to the environment. */ @@ -1692,10 +1689,7 @@ type TypeDecorator> = (target: Constructor) => void; /** Common type constants. */ export namespace types { - /** - * Basic type wire types. - * @const - */ + /** Basic type wire types. */ const basic: { "double": number, "float": number, @@ -1714,10 +1708,7 @@ export namespace types { "bytes": number }; - /** - * Basic type defaults. - * @const - */ + /** Basic type defaults. */ const defaults: { "double": number, "float": number, @@ -1737,10 +1728,7 @@ export namespace types { "message": null }; - /** - * Basic long type wire types. - * @const - */ + /** Basic long type wire types. */ const long: { "int64": number, "uint64": number, @@ -1749,10 +1737,7 @@ export namespace types { "sfixed64": number }; - /** - * Allowed types for map keys with their associated wire type. - * @const - */ + /** Allowed types for map keys with their associated wire type. */ const mapKey: { "int32": number, "uint32": number, @@ -1768,10 +1753,7 @@ export namespace types { "string": number }; - /** - * Allowed types for packed repeated fields with their associated wire type. - * @const - */ + /** Allowed types for packed repeated fields with their associated wire type. */ const packed: { "double": number, "float": number, @@ -1789,19 +1771,30 @@ export namespace types { }; } -/** - * Constructor type. - * @tstype new(...params: any[]): T; prototype: T; - */ +/** Constructor type. */ export interface Constructor extends Function { new(...params: any[]): T; prototype: T; } +/** Properties type. */ +type Properties = { [P in keyof T]?: T[P] }; + /** - * Properties type. - * @tstype { [P in keyof T]?: T[P] } + * Any compatible Buffer instance. + * This is a minimal stand-alone definition of a Buffer instance. The actual type is that exported by node's typings. */ -type Properties = { [P in keyof T]?: T[P] }; +export interface Buffer extends Uint8Array { +} + +/** + * Any compatible Long instance. + * This is a minimal stand-alone definition of a Long instance. The actual type is that exported by long.js. + */ +export interface Long { + low: number; + high: number; + unsigned: boolean; +} /** * A OneOf getter as returned by {@link util.oneOfGetter}. @@ -1906,22 +1899,13 @@ export namespace util { public length(): number; } - /** - * An immuable empty array. - * @const - */ + /** An immuable empty array. */ const emptyArray: any[]; - /** - * An immutable empty object. - * @const - */ + /** An immutable empty object. */ const emptyObject: object; - /** - * Whether running within node or not. - * @const - */ + /** Whether running within node or not. */ const isNode: boolean; /** @@ -1978,22 +1962,13 @@ export namespace util { /** Long.js's Long class if available. */ let Long: Constructor; - /** - * Regular expression used to verify 2 bit (`bool`) map keys. - * @const - */ + /** Regular expression used to verify 2 bit (`bool`) map keys. */ const key2Re: RegExp; - /** - * Regular expression used to verify 32 bit (`int32` etc.) map keys. - * @const - */ + /** Regular expression used to verify 32 bit (`int32` etc.) map keys. */ const key32Re: RegExp; - /** - * Regular expression used to verify 64 bit (`int64` etc.) map keys. - * @const - */ + /** Regular expression used to verify 64 bit (`int64` etc.) map keys. */ const key64Re: RegExp; /** @@ -2407,16 +2382,13 @@ export namespace util { */ export function verifier(mtype: Type): Codegen; -/** - * Wrappers for common types. - * @const - */ +/** Wrappers for common types. */ export const wrappers: { [k: string]: IWrapper }; /** * From object converter part of an {@link IWrapper}. * @param object Plain object - * @returns + * @returns Message instance */ type WrapperFromObjectConverter = (this: Type, object: { [k: string]: any }) => Message<{}>; @@ -2424,7 +2396,7 @@ type WrapperFromObjectConverter = (this: Type, object: { [k: string]: any }) => * To object converter part of an {@link IWrapper}. * @param message Message instance * @param [options] Conversion options - * @returns + * @returns Plain object */ type WrapperToObjectConverter = (this: Type, message: Message<{}>, options?: IConversionOptions) => { [k: string]: any }; diff --git a/src/util/minimal.js b/src/util/minimal.js index b24da6c9a..ea4655713 100644 --- a/src/util/minimal.js +++ b/src/util/minimal.js @@ -99,11 +99,11 @@ util.isSet = function isSet(obj, prop) { return false; }; -/* +/** * Any compatible Buffer instance. * This is a minimal stand-alone definition of a Buffer instance. The actual type is that exported by node's typings. - * @typedef Buffer - * @type {Uint8Array} + * @interface Buffer + * @extends Uint8Array */ /** @@ -164,11 +164,10 @@ util.newBuffer = function newBuffer(sizeOrArray) { */ util.Array = typeof Uint8Array !== "undefined" ? Uint8Array /* istanbul ignore next */ : Array; -/* +/** * Any compatible Long instance. * This is a minimal stand-alone definition of a Long instance. The actual type is that exported by long.js. - * @typedef Long - * @type {Object} + * @interface Long * @property {number} low Low bits * @property {number} high High bits * @property {boolean} unsigned Whether unsigned or not diff --git a/src/wrappers.js b/src/wrappers.js index 7f41e2ff7..f1ed2716c 100644 --- a/src/wrappers.js +++ b/src/wrappers.js @@ -14,7 +14,7 @@ var Message = require("./message"); * @typedef WrapperFromObjectConverter * @type {function} * @param {Object.} object Plain object - * @returns {Message<{}>} + * @returns {Message<{}>} Message instance * @this Type */ @@ -24,7 +24,7 @@ var Message = require("./message"); * @type {function} * @param {Message<{}>} message Message instance * @param {IConversionOptions} [options] Conversion options - * @returns {Object.} + * @returns {Object.} Plain object * @this Type */ diff --git a/stub-long.d.ts b/stub-long.d.ts deleted file mode 100644 index 575d35495..000000000 --- a/stub-long.d.ts +++ /dev/null @@ -1,4 +0,0 @@ -// minimal stub for Long instances for reference when not using long.js, -// i.e. - -type Long = number; diff --git a/stub-node.d.ts b/stub-node.d.ts deleted file mode 100644 index 867fcb5bc..000000000 --- a/stub-node.d.ts +++ /dev/null @@ -1,4 +0,0 @@ -// minimal stub for node types for reference when not using node, -// i.e. - -type Buffer = Uint8Array; diff --git a/tests/data/test.d.ts b/tests/data/test.d.ts index 2ba2302bc..f9e5319b1 100644 --- a/tests/data/test.d.ts +++ b/tests/data/test.d.ts @@ -334,6 +334,9 @@ export namespace jspb { public static fromObject(object: { [k: string]: any }): jspb.test.DefaultValues; public static toObject(message: jspb.test.DefaultValues, options?: $protobuf.IConversionOptions): { [k: string]: any }; public toJSON(): { [k: string]: any }; + } + + namespace DefaultValues { enum Enum { E1 = 13, @@ -917,6 +920,9 @@ export namespace google { public static fromObject(object: { [k: string]: any }): google.protobuf.FieldDescriptorProto; public static toObject(message: google.protobuf.FieldDescriptorProto, options?: $protobuf.IConversionOptions): { [k: string]: any }; public toJSON(): { [k: string]: any }; + } + + namespace FieldDescriptorProto { enum Type { TYPE_DOUBLE = 1, @@ -1104,6 +1110,9 @@ export namespace google { public static fromObject(object: { [k: string]: any }): google.protobuf.FileOptions; public static toObject(message: google.protobuf.FileOptions, options?: $protobuf.IConversionOptions): { [k: string]: any }; public toJSON(): { [k: string]: any }; + } + + namespace FileOptions { enum OptimizeMode { SPEED = 1, @@ -1166,6 +1175,9 @@ export namespace google { public static fromObject(object: { [k: string]: any }): google.protobuf.FieldOptions; public static toObject(message: google.protobuf.FieldOptions, options?: $protobuf.IConversionOptions): { [k: string]: any }; public toJSON(): { [k: string]: any }; + } + + namespace FieldOptions { enum CType { STRING = 0, @@ -1282,6 +1294,9 @@ export namespace google { public static fromObject(object: { [k: string]: any }): google.protobuf.MethodOptions; public static toObject(message: google.protobuf.MethodOptions, options?: $protobuf.IConversionOptions): { [k: string]: any }; public toJSON(): { [k: string]: any }; + } + + namespace MethodOptions { enum IdempotencyLevel { IDEMPOTENCY_UNKNOWN = 0,