Permalink
Browse files

Other: Even more documentation and typings for ext/descriptor

  • Loading branch information...
dcodeIO committed Apr 14, 2017
1 parent 773e634 commit 5bc3541d2da19e2857dc884f743d37c27e8e21f2
Showing with 266 additions and 144 deletions.
  1. +1 −0 .codeclimate.yml
  2. +4 −6 README.md
  3. +47 −34 ext/descriptor/README.md
  4. +65 −45 ext/descriptor/index.d.ts
  5. +149 −59 ext/descriptor/index.js
@@ -21,6 +21,7 @@ ratings:
- "lib/path/**.js"
- "lib/pool/**.js"
- "lib/utf8/**.js"
- "ext/**.js"
- "**/*.d.ts"
exclude_paths:
- "dist/**"
@@ -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
--------
@@ -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>`).
@@ -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;
Oops, something went wrong.

0 comments on commit 5bc3541

Please sign in to comment.