Other: Even more documentation and typings for ext/descriptor

protobufjs · Apr 14, 2017 · 5bc3541 · 5bc3541
1 parent 773e634
commit 5bc3541
Show file tree

Hide file tree

Showing 5 changed files with 266 additions and 144 deletions.
diff --git a/.codeclimate.yml b/.codeclimate.yml
@@ -21,6 +21,7 @@ ratings:
   - "lib/path/**.js"
   - "lib/pool/**.js"
   - "lib/utf8/**.js"
+  - "ext/**.js"
   - "**/*.d.ts"
 exclude_paths:
   - "dist/**"

diff --git a/README.md b/README.md
@@ -15,8 +15,7 @@ Contents
   A brief introduction to using the toolset.
 
   * [Valid Message](#valid-message)
-  * [Toolset](#toolset)
-
+  * [Toolset](#toolset)<br />
 
 * [Examples](#examples)<br />
   A few examples to get you started.
@@ -26,17 +25,15 @@ Contents
   * [Using reflection only](#using-reflection-only)
   * [Using custom classes](#using-custom-classes)
   * [Using services](#using-services)
-  * [Usage with TypeScript](#usage-with-typescript)
-
+  * [Usage with TypeScript](#usage-with-typescript)<br />
 
 * [Command line](#command-line)<br />
   How to use the command line utility.
 
   * [pbjs for JavaScript](#pbjs-for-javascript)
   * [pbts for TypeScript](#pbts-for-typescript)
   * [Reflection vs. static code](#reflection-vs-static-code)
-  * [Command line API](#command-line-api)
-
+  * [Command line API](#command-line-api)<br />
 
 * [Additional documentation](#additional-documentation)<br />
   A list of available documentation resources.
@@ -836,6 +833,7 @@ Compatibility
 * Support for pre-ES5 environments (except IE8) can be achieved by [using a polyfill](https://github.com/dcodeIO/protobuf.js/blob/master/scripts/polyfill.js).
 * Support for [Content Security Policy](https://w3c.github.io/webappsec-csp/)-restricted environments (like Chrome extensions without [unsafe-eval](https://developer.chrome.com/extensions/contentSecurityPolicy#relaxing-eval)) can be achieved by generating and using static code instead.
 * If a proper way to work with 64 bit values (uint64, int64 etc.) is required, just install [long.js](https://github.com/dcodeIO/long.js) alongside this library. All 64 bit numbers will then be returned as a `Long` instance instead of a possibly unsafe JavaScript number ([see](https://github.com/dcodeIO/long.js)).
+* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/dcodeIO/protobuf.js/tree/master/ext/descriptor)
 
 Building
 --------

diff --git a/ext/descriptor/README.md b/ext/descriptor/README.md
@@ -7,53 +7,66 @@ Usage
 -----
 
 ```js
-var protobuf   = require("protobufjs"),
+var protobuf   = require("protobufjs"), // requires the full library
     descriptor = require("protobufjs/ext/descriptor");
 
-// take any extisting root object
 var root = ...;
 
-// convert it to the corresponding descriptor type
-var fileDescriptorSet = root.toDescriptor("proto2");
+// convert any existing root instance to the corresponding descriptor type
+var descriptor = root.toDescriptor("proto2");
+// ^ returns a FileDescriptorSet message, see table below
 
-// encode it
-var buffer = descriptor.FileDescriptorSet.encode(fileDescriptorSet).finish();
+// encode to a descriptor buffer
+var buffer = descriptor.FileDescriptorSet.encode(descriptor).finish();
 
-// decode it back
-var decoded = descriptor.FileDescriptorSet.decode(buffer);
+// decode from a descriptor buffer
+var decodedDescriptor = descriptor.FileDescriptorSet.decode(buffer);
 
-// convert it back to a protobuf.js root
-root = protobuf.Root.fromDescriptor(decoded);
+// convert any existing descriptor to a root instance
+root = protobuf.Root.fromDescriptor(decodedDescriptor);
+// ^ expects a FileDescriptorSet message or buffer, see table below
 
 // and start all over again
 ```
 
 API
 ---
 
-The extension adds `.fromDescriptor(descriptor[, syntax])` and `#toDescriptor([syntax])` methods to reflection objects and exports the `.google.protobuf` namespace of the internally used `Root` instance containing the following types present in descriptor.proto, including sub-types:
-
-| Descriptor type          | protobuf.js type | Remarks
-|--------------------------|------------------|---------
-| FileDescriptorSet        | Root             |
-| FileDescriptorProto      | Root             | except dependencies
-| FileOptions              | Root             |
-| DescriptorProto          | Type             |
-| MessageOptions           | Type             |
-| FieldDescriptorProto     | Field            |
-| FieldOptions             | Field            |
-| OneofDescriptorProto     | OneOf            |
-| OneofOptions             | OneOf            |
-| EnumDescriptorProto      | Enum             |
-| EnumValueDescriptorProto | Enum             |
-| EnumOptions              | Enum             |
-| EnumValueOptions         | Enum             | not supported
-| ServiceDescriptorProto   | Service          |
-| ServiceOptions           | Service          |
-| MethodDescriptorProto    | Method           |
-| MethodOptions            | Method           |
-| UninterpretedOption      |                  | not supported
-| SourceCodeInfo           |                  | not supported
-| GeneratedCodeInfo        |                  | not supported
+The extension adds `.fromDescriptor(descriptor[, syntax])` and `#toDescriptor([syntax])` methods to reflection objects and exports the `.google.protobuf` namespace of the internally used `Root` instance containing the following types present in descriptor.proto:
+
+| Descriptor type                | protobuf.js type | Remarks
+|--------------------------------|------------------|---------
+| **FileDescriptorSet**          | Root             |
+| FileDescriptorProto            |                  | dependencies are not supported
+| FileOptions                    |                  |
+| FileOptions_OptimizeMode       |                  |
+| SourceCodeInfo                 |                  | not supported
+| SourceCodeInfo_Location        |                  |
+| GeneratedCodeInfo              |                  | not supported
+| GeneratedCodeInfo_Annotation   |                  |
+| **DescriptorProto**            | Type             |
+| MessageOptions                 |                  |
+| DescriptorProto_ExtensionRange |                  |
+| DescriptorProto_ReservedRange  |                  |
+| **FieldDescriptorProto**       | Field            |
+| FieldDescriptorProto_Label     |                  |
+| FieldDescriptorProto_Type      |                  |
+| FieldOptions                   |                  |
+| FieldOptions_CType             |                  |
+| FieldOptions_JSType            |                  |
+| **OneofDescriptorProto**       | OneOf            |
+| OneofOptions                   |                  |
+| **EnumDescriptorProto**        | Enum             |
+| EnumOptions                    |                  |
+| EnumValueDescriptorProto       |                  |
+| EnumValueOptions               |                  | not supported
+| **ServiceDescriptorProto**     | Service          |
+| ServiceOptions                 |                  |
+| **MethodDescriptorProto**      | Method           |
+| MethodOptions                  |                  |
+| UninterpretedOption            |                  | not supported
+| UninterpretedOption_NamePart   |                  |
 
 Note that not all features of descriptor.proto translate perfectly to a protobuf.js root instance. A root instance has only limited knowlege of packages or individual files for example, which is then compensated by guessing and generating fictional file names.
+
+When using TypeScript, the respective `...$Properties` types can be used to reference specific message types (i.e. `protobuf.Message<DescriptorProto$Properties>`).
diff --git a/ext/descriptor/index.d.ts b/ext/descriptor/index.d.ts
@@ -1,31 +1,31 @@
 import * as $protobuf from "../..";
 
-type FileDescriptorSetProperties = {
-    file: FileDescriptorProtoProperties[];
+type FileDescriptorSet$Properties = {
+    file: FileDescriptorProto$Properties[];
 };
 
-type FileDescriptorProtoProperties = {
+type FileDescriptorProto$Properties = {
     name?: string;
     package?: string;
     dependency?: any;
     publicDependency?: any;
     weakDependency?: any;
-    messageType?: DescriptorProtoProperties[];
-    enumType?: EnumDescriptorProtoProperties[];
-    service?: ServiceDescriptorProtoProperties[];
-    extension?: FieldDescriptorProtoProperties[];
-    options?: FileOptionsProperties;
+    messageType?: DescriptorProto$Properties[];
+    enumType?: EnumDescriptorProto$Properties[];
+    service?: ServiceDescriptorProto$Properties[];
+    extension?: FieldDescriptorProto$Properties[];
+    options?: FileOptions$Properties;
     sourceCodeInfo?: any;
     syntax?: string;
 };
 
-type FileOptionsProperties = {
+type FileOptions$Properties = {
     javaPackage?: string;
     javaOuterClassname?: string;
     javaMultipleFiles?: boolean;
     javaGenerateEqualsAndHash?: boolean;
     javaStringCheckUtf8?: boolean;
-    optimizeFor?: FileOptions_OptimizeMode;
+    optimizeFor?: FileOptions$OptimizeMode;
     goPackage?: string;
     ccGenericServices?: boolean;
     javaGenericServices?: boolean;
@@ -36,101 +36,101 @@ type FileOptionsProperties = {
     csharpNamespace?: string;
 };
 
-type FileOptions_OptimizeMode = number;
+type FileOptions$OptimizeMode = number;
 
-type DescriptorProtoProperties = {
+type DescriptorProto$Properties = {
     name?: string;
-    field?: FieldDescriptorProtoProperties[];
-    extension?: FieldDescriptorProtoProperties[];
-    nestedType?: DescriptorProtoProperties[];
-    enumType?: EnumDescriptorProtoProperties[];
-    extensionRange?: ExtensionRangeProperties[];
-    oneofDecl?: OneofDescriptorProtoProperties[];
-    options?: MessageOptionsProperties;
-    reservedRange?: ReservedRangeProperties[];
+    field?: FieldDescriptorProto$Properties[];
+    extension?: FieldDescriptorProto$Properties[];
+    nestedType?: DescriptorProto$Properties[];
+    enumType?: EnumDescriptorProto$Properties[];
+    extensionRange?: ExtensionRange$Properties[];
+    oneofDecl?: OneofDescriptorProto$Properties[];
+    options?: MessageOptions$Properties;
+    reservedRange?: ReservedRange$Properties[];
     reservedName?: string[];
 };
 
-type MessageOptionsProperties = {
+type MessageOptions$Properties = {
     mapEntry?: boolean;
 };
 
-type ExtensionRangeProperties = {
+type ExtensionRange$Properties = {
     start?: number;
     end?: number;
 };
 
-type ReservedRangeProperties = {
+type ReservedRange$Properties = {
     start?: number;
     end?: number;
 };
 
-type FieldDescriptorProtoProperties = {
+type FieldDescriptorProto$Properties = {
     name?: string;
     number?: number;
-    label?: FieldDescriptorProto_Label;
-    type?: FieldDescriptorProto_Type;
+    label?: FieldDescriptorProto$Label;
+    type?: FieldDescriptorProto$Type;
     typeName?: string;
     extendee?: string;
     defaultValue?: string;
     oneofIndex?: number;
     jsonName?: any;
-    options?: FieldOptionsProperties;
+    options?: FieldOptions$Properties;
 };
 
-type FieldDescriptorProto_Label = number;
+type FieldDescriptorProto$Label = number;
 
-type FieldDescriptorProto_Type = number;
+type FieldDescriptorProto$Type = number;
 
-type FieldOptionsProperties = {
+type FieldOptions$Properties = {
     packed?: boolean;
-    jstype?: FieldOptions_JSType;
+    jstype?: FieldOptions$JSType;
 };
 
-type FieldOptions_JSType = number;
+type FieldOptions$JSType = number;
 
-type EnumDescriptorProtoProperties = {
+type EnumDescriptorProto$Properties = {
     name?: string;
-    value?: EnumValueDescriptorProtoProperties[];
-    options?: EnumOptionsProperties;
+    value?: EnumValueDescriptorProto$Properties[];
+    options?: EnumOptions$Properties;
 };
 
-type EnumValueDescriptorProtoProperties = {
+type EnumValueDescriptorProto$Properties = {
     name?: string;
     number?: number;
     options?: any;
 };
 
-type EnumOptionsProperties = {
+type EnumOptions$Properties = {
     allowAlias?: boolean;
     deprecated?: boolean;
 };
 
-type OneofDescriptorProtoProperties = {
+type OneofDescriptorProto$Properties = {
     name?: string;
     options?: any;
 };
 
-type ServiceDescriptorProtoProperties = {
+type ServiceDescriptorProto$Properties = {
     name?: string;
-    method?: MethodDescriptorProtoProperties[];
-    options?: ServiceOptionsProperties;
+    method?: MethodDescriptorProto$Properties[];
+    options?: ServiceOptions$Properties;
 };
 
-type ServiceOptionsProperties = {
+type ServiceOptions$Properties = {
     deprecated?: boolean;
 };
 
-type MethodDescriptorProtoProperties = {
+type MethodDescriptorProto$Properties = {
     name?: string;
     inputType?: string;
     outputType?: string;
-    options?: MethodOptionsProperties;
+    options?: MethodOptions$Properties;
     clientStreaming?: boolean;
     serverStreaming?: boolean;
 };
 
-type MethodOptionsProperties = {
+type MethodOptions$Properties = {
     deprecated?: boolean;
 };
 
@@ -140,8 +140,16 @@ export const FileDescriptorProto: $protobuf.Type;
 
 export const DescriptorProto: $protobuf.Type;
 
+export const DescriptorProto_ExtensionRange: $protobuf.Type;
+
+export const DescriptorProto_ReservedRange: $protobuf.Type;
+
 export const FieldDescriptorProto: $protobuf.Type;
 
+export const FieldDescriptorProto_Label: $protobuf.Enum;
+
+export const FieldDescriptorProto_Type: $protobuf.Enum;
+
 export const OneofDescriptorProto: $protobuf.Type;
 
 export const EnumDescriptorProto: $protobuf.Type;
@@ -154,10 +162,16 @@ export const MethodDescriptorProto: $protobuf.Type;
 
 export const FileOptions: $protobuf.Type;
 
+export const FileOptions_OptimizeMode: $protobuf.Enum;
+
 export const MessageOptions: $protobuf.Type;
 
 export const FieldOptions: $protobuf.Type;
 
+export const FieldOptions_CType: $protobuf.Enum;
+
+export const FieldOptions_JSType: $protobuf.Enum;
+
 export const OneofOptions: $protobuf.Type;
 
 export const EnumOptions: $protobuf.Type;
@@ -170,6 +184,12 @@ export const MethodOptions: $protobuf.Type;
 
 export const UninterpretedOption: $protobuf.Type;
 
+export const UninterpretedOption_NamePart: $protobuf.Type;
+
 export const SourceCodeInfo: $protobuf.Type;
 
+export const SourceCodeInfo_Location: $protobuf.Type;
+
 export const GeneratedCodeInfo: $protobuf.Type;
+
+export const GeneratedCodeInfo_Annotation: $protobuf.Type;