Skip to content

Commit 5bc3541

Browse files
dcodeIOdcodeIO
committed
Other: Even more documentation and typings for ext/descriptor
1 parent 773e634 commit 5bc3541

File tree

5 files changed

+266
-144
lines changed

5 files changed

+266
-144
lines changed

‎.codeclimate.yml

+1
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ ratings:
2121
- "lib/path/**.js"
2222
- "lib/pool/**.js"
2323
- "lib/utf8/**.js"
24+
- "ext/**.js"
2425
- "**/*.d.ts"
2526
exclude_paths:
2627
- "dist/**"

‎README.md

+4-6
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,7 @@ Contents
1515
A brief introduction to using the toolset.
1616

1717
* [Valid Message](#valid-message)
18-
* [Toolset](#toolset)
19-
18+
* [Toolset](#toolset)<br />
2019

2120
* [Examples](#examples)<br />
2221
A few examples to get you started.
@@ -26,17 +25,15 @@ Contents
2625
* [Using reflection only](#using-reflection-only)
2726
* [Using custom classes](#using-custom-classes)
2827
* [Using services](#using-services)
29-
* [Usage with TypeScript](#usage-with-typescript)
30-
28+
* [Usage with TypeScript](#usage-with-typescript)<br />
3129

3230
* [Command line](#command-line)<br />
3331
How to use the command line utility.
3432

3533
* [pbjs for JavaScript](#pbjs-for-javascript)
3634
* [pbts for TypeScript](#pbts-for-typescript)
3735
* [Reflection vs. static code](#reflection-vs-static-code)
38-
* [Command line API](#command-line-api)
39-
36+
* [Command line API](#command-line-api)<br />
4037

4138
* [Additional documentation](#additional-documentation)<br />
4239
A list of available documentation resources.
@@ -836,6 +833,7 @@ Compatibility
836833
* 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).
837834
* 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.
838835
* 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)).
836+
* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/dcodeIO/protobuf.js/tree/master/ext/descriptor)
839837

840838
Building
841839
--------

‎ext/descriptor/README.md

+47-34
Original file line numberDiff line numberDiff line change
@@ -7,53 +7,66 @@ Usage
77
-----
88

99
```js
10-
var protobuf = require("protobufjs"),
10+
var protobuf = require("protobufjs"), // requires the full library
1111
descriptor = require("protobufjs/ext/descriptor");
1212

13-
// take any extisting root object
1413
var root = ...;
1514

16-
// convert it to the corresponding descriptor type
17-
var fileDescriptorSet = root.toDescriptor("proto2");
15+
// convert any existing root instance to the corresponding descriptor type
16+
var descriptor = root.toDescriptor("proto2");
17+
// ^ returns a FileDescriptorSet message, see table below
1818

19-
// encode it
20-
var buffer = descriptor.FileDescriptorSet.encode(fileDescriptorSet).finish();
19+
// encode to a descriptor buffer
20+
var buffer = descriptor.FileDescriptorSet.encode(descriptor).finish();
2121

22-
// decode it back
23-
var decoded = descriptor.FileDescriptorSet.decode(buffer);
22+
// decode from a descriptor buffer
23+
var decodedDescriptor = descriptor.FileDescriptorSet.decode(buffer);
2424

25-
// convert it back to a protobuf.js root
26-
root = protobuf.Root.fromDescriptor(decoded);
25+
// convert any existing descriptor to a root instance
26+
root = protobuf.Root.fromDescriptor(decodedDescriptor);
27+
// ^ expects a FileDescriptorSet message or buffer, see table below
2728

2829
// and start all over again
2930
```
3031

3132
API
3233
---
3334

34-
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:
35-
36-
| Descriptor type | protobuf.js type | Remarks
37-
|--------------------------|------------------|---------
38-
| FileDescriptorSet | Root |
39-
| FileDescriptorProto | Root | except dependencies
40-
| FileOptions | Root |
41-
| DescriptorProto | Type |
42-
| MessageOptions | Type |
43-
| FieldDescriptorProto | Field |
44-
| FieldOptions | Field |
45-
| OneofDescriptorProto | OneOf |
46-
| OneofOptions | OneOf |
47-
| EnumDescriptorProto | Enum |
48-
| EnumValueDescriptorProto | Enum |
49-
| EnumOptions | Enum |
50-
| EnumValueOptions | Enum | not supported
51-
| ServiceDescriptorProto | Service |
52-
| ServiceOptions | Service |
53-
| MethodDescriptorProto | Method |
54-
| MethodOptions | Method |
55-
| UninterpretedOption | | not supported
56-
| SourceCodeInfo | | not supported
57-
| GeneratedCodeInfo | | not supported
35+
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:
36+
37+
| Descriptor type | protobuf.js type | Remarks
38+
|--------------------------------|------------------|---------
39+
| **FileDescriptorSet** | Root |
40+
| FileDescriptorProto | | dependencies are not supported
41+
| FileOptions | |
42+
| FileOptions_OptimizeMode | |
43+
| SourceCodeInfo | | not supported
44+
| SourceCodeInfo_Location | |
45+
| GeneratedCodeInfo | | not supported
46+
| GeneratedCodeInfo_Annotation | |
47+
| **DescriptorProto** | Type |
48+
| MessageOptions | |
49+
| DescriptorProto_ExtensionRange | |
50+
| DescriptorProto_ReservedRange | |
51+
| **FieldDescriptorProto** | Field |
52+
| FieldDescriptorProto_Label | |
53+
| FieldDescriptorProto_Type | |
54+
| FieldOptions | |
55+
| FieldOptions_CType | |
56+
| FieldOptions_JSType | |
57+
| **OneofDescriptorProto** | OneOf |
58+
| OneofOptions | |
59+
| **EnumDescriptorProto** | Enum |
60+
| EnumOptions | |
61+
| EnumValueDescriptorProto | |
62+
| EnumValueOptions | | not supported
63+
| **ServiceDescriptorProto** | Service |
64+
| ServiceOptions | |
65+
| **MethodDescriptorProto** | Method |
66+
| MethodOptions | |
67+
| UninterpretedOption | | not supported
68+
| UninterpretedOption_NamePart | |
5869

5970
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.
71+
72+
When using TypeScript, the respective `...$Properties` types can be used to reference specific message types (i.e. `protobuf.Message<DescriptorProto$Properties>`).

‎ext/descriptor/index.d.ts

+65-45
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,31 @@
11
import * as $protobuf from "../..";
22

3-
type FileDescriptorSetProperties = {
4-
file: FileDescriptorProtoProperties[];
3+
type FileDescriptorSet$Properties = {
4+
file: FileDescriptorProto$Properties[];
55
};
66

7-
type FileDescriptorProtoProperties = {
7+
type FileDescriptorProto$Properties = {
88
name?: string;
99
package?: string;
1010
dependency?: any;
1111
publicDependency?: any;
1212
weakDependency?: any;
13-
messageType?: DescriptorProtoProperties[];
14-
enumType?: EnumDescriptorProtoProperties[];
15-
service?: ServiceDescriptorProtoProperties[];
16-
extension?: FieldDescriptorProtoProperties[];
17-
options?: FileOptionsProperties;
13+
messageType?: DescriptorProto$Properties[];
14+
enumType?: EnumDescriptorProto$Properties[];
15+
service?: ServiceDescriptorProto$Properties[];
16+
extension?: FieldDescriptorProto$Properties[];
17+
options?: FileOptions$Properties;
1818
sourceCodeInfo?: any;
1919
syntax?: string;
2020
};
2121

22-
type FileOptionsProperties = {
22+
type FileOptions$Properties = {
2323
javaPackage?: string;
2424
javaOuterClassname?: string;
2525
javaMultipleFiles?: boolean;
2626
javaGenerateEqualsAndHash?: boolean;
2727
javaStringCheckUtf8?: boolean;
28-
optimizeFor?: FileOptions_OptimizeMode;
28+
optimizeFor?: FileOptions$OptimizeMode;
2929
goPackage?: string;
3030
ccGenericServices?: boolean;
3131
javaGenericServices?: boolean;
@@ -36,101 +36,101 @@ type FileOptionsProperties = {
3636
csharpNamespace?: string;
3737
};
3838

39-
type FileOptions_OptimizeMode = number;
39+
type FileOptions$OptimizeMode = number;
4040

41-
type DescriptorProtoProperties = {
41+
type DescriptorProto$Properties = {
4242
name?: string;
43-
field?: FieldDescriptorProtoProperties[];
44-
extension?: FieldDescriptorProtoProperties[];
45-
nestedType?: DescriptorProtoProperties[];
46-
enumType?: EnumDescriptorProtoProperties[];
47-
extensionRange?: ExtensionRangeProperties[];
48-
oneofDecl?: OneofDescriptorProtoProperties[];
49-
options?: MessageOptionsProperties;
50-
reservedRange?: ReservedRangeProperties[];
43+
field?: FieldDescriptorProto$Properties[];
44+
extension?: FieldDescriptorProto$Properties[];
45+
nestedType?: DescriptorProto$Properties[];
46+
enumType?: EnumDescriptorProto$Properties[];
47+
extensionRange?: ExtensionRange$Properties[];
48+
oneofDecl?: OneofDescriptorProto$Properties[];
49+
options?: MessageOptions$Properties;
50+
reservedRange?: ReservedRange$Properties[];
5151
reservedName?: string[];
5252
};
5353

54-
type MessageOptionsProperties = {
54+
type MessageOptions$Properties = {
5555
mapEntry?: boolean;
5656
};
5757

58-
type ExtensionRangeProperties = {
58+
type ExtensionRange$Properties = {
5959
start?: number;
6060
end?: number;
6161
};
6262

63-
type ReservedRangeProperties = {
63+
type ReservedRange$Properties = {
6464
start?: number;
6565
end?: number;
6666
};
6767

68-
type FieldDescriptorProtoProperties = {
68+
type FieldDescriptorProto$Properties = {
6969
name?: string;
7070
number?: number;
71-
label?: FieldDescriptorProto_Label;
72-
type?: FieldDescriptorProto_Type;
71+
label?: FieldDescriptorProto$Label;
72+
type?: FieldDescriptorProto$Type;
7373
typeName?: string;
7474
extendee?: string;
7575
defaultValue?: string;
7676
oneofIndex?: number;
7777
jsonName?: any;
78-
options?: FieldOptionsProperties;
78+
options?: FieldOptions$Properties;
7979
};
8080

81-
type FieldDescriptorProto_Label = number;
81+
type FieldDescriptorProto$Label = number;
8282

83-
type FieldDescriptorProto_Type = number;
83+
type FieldDescriptorProto$Type = number;
8484

85-
type FieldOptionsProperties = {
85+
type FieldOptions$Properties = {
8686
packed?: boolean;
87-
jstype?: FieldOptions_JSType;
87+
jstype?: FieldOptions$JSType;
8888
};
8989

90-
type FieldOptions_JSType = number;
90+
type FieldOptions$JSType = number;
9191

92-
type EnumDescriptorProtoProperties = {
92+
type EnumDescriptorProto$Properties = {
9393
name?: string;
94-
value?: EnumValueDescriptorProtoProperties[];
95-
options?: EnumOptionsProperties;
94+
value?: EnumValueDescriptorProto$Properties[];
95+
options?: EnumOptions$Properties;
9696
};
9797

98-
type EnumValueDescriptorProtoProperties = {
98+
type EnumValueDescriptorProto$Properties = {
9999
name?: string;
100100
number?: number;
101101
options?: any;
102102
};
103103

104-
type EnumOptionsProperties = {
104+
type EnumOptions$Properties = {
105105
allowAlias?: boolean;
106106
deprecated?: boolean;
107107
};
108108

109-
type OneofDescriptorProtoProperties = {
109+
type OneofDescriptorProto$Properties = {
110110
name?: string;
111111
options?: any;
112112
};
113113

114-
type ServiceDescriptorProtoProperties = {
114+
type ServiceDescriptorProto$Properties = {
115115
name?: string;
116-
method?: MethodDescriptorProtoProperties[];
117-
options?: ServiceOptionsProperties;
116+
method?: MethodDescriptorProto$Properties[];
117+
options?: ServiceOptions$Properties;
118118
};
119119

120-
type ServiceOptionsProperties = {
120+
type ServiceOptions$Properties = {
121121
deprecated?: boolean;
122122
};
123123

124-
type MethodDescriptorProtoProperties = {
124+
type MethodDescriptorProto$Properties = {
125125
name?: string;
126126
inputType?: string;
127127
outputType?: string;
128-
options?: MethodOptionsProperties;
128+
options?: MethodOptions$Properties;
129129
clientStreaming?: boolean;
130130
serverStreaming?: boolean;
131131
};
132132

133-
type MethodOptionsProperties = {
133+
type MethodOptions$Properties = {
134134
deprecated?: boolean;
135135
};
136136

@@ -140,8 +140,16 @@ export const FileDescriptorProto: $protobuf.Type;
140140

141141
export const DescriptorProto: $protobuf.Type;
142142

143+
export const DescriptorProto_ExtensionRange: $protobuf.Type;
144+
145+
export const DescriptorProto_ReservedRange: $protobuf.Type;
146+
143147
export const FieldDescriptorProto: $protobuf.Type;
144148

149+
export const FieldDescriptorProto_Label: $protobuf.Enum;
150+
151+
export const FieldDescriptorProto_Type: $protobuf.Enum;
152+
145153
export const OneofDescriptorProto: $protobuf.Type;
146154

147155
export const EnumDescriptorProto: $protobuf.Type;
@@ -154,10 +162,16 @@ export const MethodDescriptorProto: $protobuf.Type;
154162

155163
export const FileOptions: $protobuf.Type;
156164

165+
export const FileOptions_OptimizeMode: $protobuf.Enum;
166+
157167
export const MessageOptions: $protobuf.Type;
158168

159169
export const FieldOptions: $protobuf.Type;
160170

171+
export const FieldOptions_CType: $protobuf.Enum;
172+
173+
export const FieldOptions_JSType: $protobuf.Enum;
174+
161175
export const OneofOptions: $protobuf.Type;
162176

163177
export const EnumOptions: $protobuf.Type;
@@ -170,6 +184,12 @@ export const MethodOptions: $protobuf.Type;
170184

171185
export const UninterpretedOption: $protobuf.Type;
172186

187+
export const UninterpretedOption_NamePart: $protobuf.Type;
188+
173189
export const SourceCodeInfo: $protobuf.Type;
174190

191+
export const SourceCodeInfo_Location: $protobuf.Type;
192+
175193
export const GeneratedCodeInfo: $protobuf.Type;
194+
195+
export const GeneratedCodeInfo_Annotation: $protobuf.Type;

0 commit comments

Comments
 (0)