protobufjs 8.1.5-experimental → 8.2.0

package/ext/README.md

@@ -0,0 +1,81 @@
+# protobuf.js Extensions
+
+## descriptor
+
+Optional `google/protobuf/descriptor.proto` interoperability layer for reflected roots and objects.
+
+```js
+import protobuf from "protobufjs";
+import descriptor from "protobufjs/ext/descriptor.js";
+
+// Convert an existing root to a FileDescriptorSet message.
+const root = protobuf.Root.fromJSON(bundle);
+const set = root.toDescriptor("proto2");
+
+// Encode descriptor buffers.
+const buffer = descriptor.FileDescriptorSet.encode(set).finish();
+
+// Convert a FileDescriptorSet message or buffer back to a root.
+const decodedRoot = protobuf.Root.fromDescriptor(buffer);
+```
+
+The extension requires reflection metadata and also works with `protobufjs/light.js` when schemas are loaded from JSON or otherwise provided as reflection objects.
+
+Importing the extension adds `.fromDescriptor(descriptor[, syntaxOrEdition])` and `#toDescriptor([syntaxOrEdition])` methods to reflection objects and exports reflected descriptor types from `google.protobuf`. Descriptor inputs can be decoded messages, readers, or `Uint8Array`s for the corresponding descriptor message.
+
+| Descriptor type               | protobuf.js type | Remarks |
+|-------------------------------|------------------|---------|
+| **FileDescriptorSet**         | Root             | |
+| FileDescriptorProto           |                  | dependencies and source info are ignored on input and not emitted |
+| FileOptions                   |                  | |
+| FileOptionsOptimizeMode       |                  | |
+| SourceCodeInfo                |                  | exported descriptor type; not mapped to reflection |
+| SourceCodeInfoLocation        |                  | |
+| GeneratedCodeInfo             |                  | exported descriptor type; not mapped to reflection |
+| GeneratedCodeInfoAnnotation   |                  | |
+| **DescriptorProto**           | Type             | |
+| MessageOptions                |                  | |
+| DescriptorProtoExtensionRange |                  | |
+| DescriptorProtoReservedRange  |                  | |
+| **FieldDescriptorProto**      | Field / MapField | map entries are reconstructed as map fields |
+| FieldDescriptorProtoLabel     |                  | |
+| FieldDescriptorProtoType      |                  | |
+| FieldOptions                  |                  | |
+| FieldOptionsCType             |                  | |
+| FieldOptionsJSType            |                  | |
+| **OneofDescriptorProto**      | OneOf            | |
+| OneofOptions                  |                  | |
+| **EnumDescriptorProto**       | Enum             | |
+| EnumOptions                   |                  | |
+| EnumValueDescriptorProto      |                  | |
+| EnumValueOptions              |                  | |
+| **ServiceDescriptorProto**    | Service          | |
+| ServiceOptions                |                  | |
+| **MethodDescriptorProto**     | Method           | |
+| MethodOptions                 |                  | |
+| FeatureSet                    |                  | exported descriptor type; used by edition-aware options |
+| FeatureSetDefaults            |                  | exported descriptor type |
+| UninterpretedOption           |                  | exported descriptor type; options are not interpreted |
+| UninterpretedOptionNamePart   |                  | |
+
+Not all `descriptor.proto` features translate perfectly to a protobuf.js root. A root has only limited knowledge of packages and individual files, for example, which is compensated by guessing and generating file names.
+
+The exported TypeScript interfaces can be used to reference specific descriptor message instances, for example `protobuf.Message<IDescriptorProto>`.
+
+## textformat
+
+Optional text format support for reflected message types.
+
+```js
+import protobuf from "protobufjs";
+import "protobufjs/ext/textformat.js";
+
+const root = protobuf.Root.fromJSON(bundle);
+const MyType = root.lookupType("MyType");
+const message = MyType.fromText("value: 1");
+const text = MyType.toText(message);
+```
+
+The extension patches `protobuf.Type` at runtime and requires reflection metadata. It works with `protobufjs/light.js` when schemas are loaded from JSON or otherwise provided as reflection objects. Static-only code using `protobufjs/minimal.js` is not supported.
+
+Text output is produced from the message object passed to `toText`. Unknown fields can be printed with numeric field names by passing `{ unknowns: true }` to `toText`.

package/ext/descriptor/README.md

@@ -1,72 +1,5 @@
-protobufjs/ext/descriptor
-=========================
+# protobufjs/ext/descriptor
 
-Experimental extension for interoperability with [descriptor.proto](https://github.com/google/protobuf/blob/master/src/google/protobuf/descriptor.proto) types.
+This directory is kept as a backwards-compatible shim for `protobufjs/ext/descriptor` and may be removed in a future major release.
 
-Usage
------
-
-```js
-var protobuf   = require("protobufjs"), // requires the full library
-    descriptor = require("protobufjs/ext/descriptor");
-
-var root = ...;
-
-// convert any existing root instance to the corresponding descriptor type
-var descriptorMsg = root.toDescriptor("proto2");
-// ^ returns a FileDescriptorSet message, see table below
-
-// encode to a descriptor buffer
-var buffer = descriptor.FileDescriptorSet.encode(descriptorMsg).finish();
-
-// decode from a descriptor buffer
-var decodedDescriptor = descriptor.FileDescriptorSet.decode(buffer);
-
-// 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:
-
-| Descriptor type               | protobuf.js type | Remarks
-|-------------------------------|------------------|---------
-| **FileDescriptorSet**         | Root             |
-| FileDescriptorProto           |                  | dependencies are not supported
-| FileOptions                   |                  |
-| FileOptionsOptimizeMode       |                  |
-| SourceCodeInfo                |                  | not supported
-| SourceCodeInfoLocation        |                  |
-| GeneratedCodeInfo             |                  | not supported
-| GeneratedCodeInfoAnnotation   |                  |
-| **DescriptorProto**           | Type             |
-| MessageOptions                |                  |
-| DescriptorProtoExtensionRange |                  |
-| DescriptorProtoReservedRange  |                  |
-| **FieldDescriptorProto**      | Field            |
-| FieldDescriptorProtoLabel     |                  |
-| FieldDescriptorProtoType      |                  |
-| FieldOptions                  |                  |
-| FieldOptionsCType             |                  |
-| FieldOptionsJSType            |                  |
-| **OneofDescriptorProto**      | OneOf            |
-| OneofOptions                  |                  |
-| **EnumDescriptorProto**       | Enum             |
-| EnumOptions                   |                  |
-| EnumValueDescriptorProto      |                  |
-| EnumValueOptions              |                  | not supported
-| **ServiceDescriptorProto**    | Service          |
-| ServiceOptions                |                  |
-| **MethodDescriptorProto**     | Method           |
-| MethodOptions                 |                  |
-| UninterpretedOption           |                  | not supported
-| UninterpretedOptionNamePart   |                  |
-
-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 interface types can be used to reference specific message instances (i.e. `protobuf.Message<IDescriptorProto>`).
+The descriptor extension documentation now lives in [../README.md](../README.md#descriptor).

package/ext/descriptor/index.d.ts

@@ -1,191 +1 @@
-import * as $protobuf from "../..";
-export const FileDescriptorSet: $protobuf.Type;
-
-export const FileDescriptorProto: $protobuf.Type;
-
-export const DescriptorProto: $protobuf.Type & {
-    ExtensionRange: $protobuf.Type,
-    ReservedRange: $protobuf.Type
-};
-
-export const FieldDescriptorProto: $protobuf.Type & {
-    Label: $protobuf.Enum,
-    Type: $protobuf.Enum
-};
-
-export const OneofDescriptorProto: $protobuf.Type;
-
-export const EnumDescriptorProto: $protobuf.Type;
-
-export const ServiceDescriptorProto: $protobuf.Type;
-
-export const EnumValueDescriptorProto: $protobuf.Type;
-
-export const MethodDescriptorProto: $protobuf.Type;
-
-export const FileOptions: $protobuf.Type & {
-    OptimizeMode: $protobuf.Enum
-};
-
-export const MessageOptions: $protobuf.Type;
-
-export const FieldOptions: $protobuf.Type & {
-    CType: $protobuf.Enum,
-    JSType: $protobuf.Enum
-};
-
-export const OneofOptions: $protobuf.Type;
-
-export const EnumOptions: $protobuf.Type;
-
-export const EnumValueOptions: $protobuf.Type;
-
-export const ServiceOptions: $protobuf.Type;
-
-export const MethodOptions: $protobuf.Type;
-
-export const UninterpretedOption: $protobuf.Type & {
-    NamePart: $protobuf.Type
-};
-
-export const SourceCodeInfo: $protobuf.Type & {
-    Location: $protobuf.Type
-};
-
-export const GeneratedCodeInfo: $protobuf.Type & {
-    Annotation: $protobuf.Type
-};
-
-export interface IFileDescriptorSet {
-    file: IFileDescriptorProto[];
-}
-
-export interface IFileDescriptorProto {
-    name?: string;
-    package?: string;
-    dependency?: any;
-    publicDependency?: any;
-    weakDependency?: any;
-    messageType?: IDescriptorProto[];
-    enumType?: IEnumDescriptorProto[];
-    service?: IServiceDescriptorProto[];
-    extension?: IFieldDescriptorProto[];
-    options?: IFileOptions;
-    sourceCodeInfo?: any;
-    syntax?: string;
-}
-
-export interface IFileOptions {
-    javaPackage?: string;
-    javaOuterClassname?: string;
-    javaMultipleFiles?: boolean;
-    javaGenerateEqualsAndHash?: boolean;
-    javaStringCheckUtf8?: boolean;
-    optimizeFor?: IFileOptionsOptimizeMode;
-    goPackage?: string;
-    ccGenericServices?: boolean;
-    javaGenericServices?: boolean;
-    pyGenericServices?: boolean;
-    deprecated?: boolean;
-    ccEnableArenas?: boolean;
-    objcClassPrefix?: string;
-    csharpNamespace?: string;
-}
-
-type IFileOptionsOptimizeMode = number;
-
-export interface IDescriptorProto {
-    name?: string;
-    field?: IFieldDescriptorProto[];
-    extension?: IFieldDescriptorProto[];
-    nestedType?: IDescriptorProto[];
-    enumType?: IEnumDescriptorProto[];
-    extensionRange?: IDescriptorProtoExtensionRange[];
-    oneofDecl?: IOneofDescriptorProto[];
-    options?: IMessageOptions;
-    reservedRange?: IDescriptorProtoReservedRange[];
-    reservedName?: string[];
-}
-
-export interface IMessageOptions {
-    mapEntry?: boolean;
-}
-
-export interface IDescriptorProtoExtensionRange {
-    start?: number;
-    end?: number;
-}
-
-export interface IDescriptorProtoReservedRange {
-    start?: number;
-    end?: number;
-}
-
-export interface IFieldDescriptorProto {
-    name?: string;
-    number?: number;
-    label?: IFieldDescriptorProtoLabel;
-    type?: IFieldDescriptorProtoType;
-    typeName?: string;
-    extendee?: string;
-    defaultValue?: string;
-    oneofIndex?: number;
-    jsonName?: any;
-    options?: IFieldOptions;
-}
-
-type IFieldDescriptorProtoLabel = number;
-
-type IFieldDescriptorProtoType = number;
-
-export interface IFieldOptions {
-    packed?: boolean;
-    jstype?: IFieldOptionsJSType;
-}
-
-type IFieldOptionsJSType = number;
-
-export interface IEnumDescriptorProto {
-    name?: string;
-    value?: IEnumValueDescriptorProto[];
-    options?: IEnumOptions;
-}
-
-export interface IEnumValueDescriptorProto {
-    name?: string;
-    number?: number;
-    options?: any;
-}
-
-export interface IEnumOptions {
-    allowAlias?: boolean;
-    deprecated?: boolean;
-}
-
-export interface IOneofDescriptorProto {
-    name?: string;
-    options?: any;
-}
-
-export interface IServiceDescriptorProto {
-    name?: string;
-    method?: IMethodDescriptorProto[];
-    options?: IServiceOptions;
-}
-
-export interface IServiceOptions {
-    deprecated?: boolean;
-}
-
-export interface IMethodDescriptorProto {
-    name?: string;
-    inputType?: string;
-    outputType?: string;
-    options?: IMethodOptions;
-    clientStreaming?: boolean;
-    serverStreaming?: boolean;
-}
-
-export interface IMethodOptions {
-    deprecated?: boolean;
-}
+export * from "../descriptor";