protobufjs 8.5.0 → 8.6.1

package/ext/README.md

@@ -2,14 +2,14 @@
 
 ## descriptor
 
-Optional `google/protobuf/descriptor.proto` interoperability layer for reflected roots and objects.
+Optional `descriptor.proto` support for converting reflected protobuf.js roots and objects to and from descriptor messages.
 
 ```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 root = ...;
 const set = root.toDescriptor("proto2");
 
 // Encode descriptor buffers.
@@ -21,61 +21,50 @@ 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>`.
+Importing the extension adds `.fromDescriptor(descriptor[, editionOrContext])` and `#toDescriptor([syntaxOrEdition])` methods to reflection objects and exports the bundled descriptor types from `google.protobuf`. Descriptor inputs can be decoded messages, readers, or buffers of the corresponding descriptor messages. Direct object descriptor imports accept either an edition string or a descriptor context with `edition`, `features` and `keepCase`.
+
+The conversion covers descriptor messages that correspond to protobuf.js reflection objects: files and file sets, messages, fields and map fields, oneofs, enums, services and methods. Descriptor-only metadata such as source locations, generated-code annotations and uninterpreted options remains available through the exported descriptor message types, but is not mapped onto reflection objects. File names are inferred when generating descriptors because roots do not retain exact file/package boundaries.
+
+## protojson
+
+Optional ProtoJSON support for reflected message types.
+
+> [!NOTE]
+> Specialized code generation for the `pbjs` static-module target is a potential future extension. If you need this for high-throughput JSON transcoding or REST fallbacks in production, consider getting in touch and supporting the codegen and conformance work.
+
+```js
+import protobuf from "protobufjs";
+import protojson from "protobufjs/ext/protojson.js";
+
+const root = ...;
+const MyType = root.lookupType("MyType");
+const message = protojson.fromJson(MyType, { value: 1 });
+const json = protojson.toJson(MyType, message);
+```
+
+```js
+const messageFromString = protojson.fromJsonString(MyType, '{"value":1}');
+const jsonString = protojson.toJsonString(MyType, messageFromString);
+```
+
+Importing the extension has no prototype side effects. Calling `protojson.install()` installs `fromJson`, `fromJsonString`, `toJson` and `toJsonString` convenience methods on `protobuf.Type.prototype`. It works with `protobufjs/light.js` when schemas are loaded from JSON or otherwise provided as reflection objects.
+
+Unknown fields can be ignored while parsing by passing `{ ignoreUnknownFields: true }` to `fromJson` or `fromJsonString`.
 
 ## textformat
 
-Optional text format support for reflected message types.
+Optional Text Format support for reflected message types.
 
 ```js
 import protobuf from "protobufjs";
-import "protobufjs/ext/textformat.js";
+import textformat from "protobufjs/ext/textformat.js";
 
-const root = protobuf.Root.fromJSON(bundle);
+const root = ...;
 const MyType = root.lookupType("MyType");
-const message = MyType.fromText("value: 1");
-const text = MyType.toText(message);
+const message = textformat.fromText(MyType, "value: 1");
+const text = textformat.toText(MyType, 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.
+Importing the extension has no prototype side effects. Calling `textformat.install()` installs `fromText` and `toText` convenience methods on `protobuf.Type.prototype`. It works with `protobufjs/light.js` when schemas are loaded from JSON or otherwise provided as reflection objects.
 
-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`.
+Unknown fields can be printed with numeric field names by passing `{ unknowns: true }` to `toText`.

package/ext/descriptor.d.ts

@@ -1,6 +1,7 @@
 import * as $protobuf from "..";
 import {
     IDescriptorProto,
+    IDescriptorContext,
     IEnumDescriptorProto,
     IFieldDescriptorProto,
     IFileDescriptorSet,
@@ -16,7 +17,7 @@ type DescriptorInput<T> = T | $protobuf.Reader | Uint8Array;
 declare module ".." {
     namespace Root {
         /** Creates a root from a descriptor set. */
-        function fromDescriptor(descriptor: DescriptorInput<IFileDescriptorSet>): $protobuf.Root;
+        function fromDescriptor(descriptor: DescriptorInput<IFileDescriptorSet>, options?: { keepCase?: boolean }): $protobuf.Root;
     }
 
     interface Root {
@@ -26,7 +27,7 @@ declare module ".." {
 
     namespace Type {
         /** Creates a type from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IDescriptorProto>, edition?: string, nested?: boolean): $protobuf.Type;
+        function fromDescriptor(descriptor: DescriptorInput<IDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.Type;
     }
 
     interface Type {
@@ -36,7 +37,7 @@ declare module ".." {
 
     namespace Field {
         /** Creates a field from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IFieldDescriptorProto>, edition?: string, nested?: boolean): $protobuf.Field;
+        function fromDescriptor(descriptor: DescriptorInput<IFieldDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.Field;
     }
 
     interface Field {
@@ -46,7 +47,7 @@ declare module ".." {
 
     namespace Enum {
         /** Creates an enum from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IEnumDescriptorProto>, edition?: string, nested?: boolean): $protobuf.Enum;
+        function fromDescriptor(descriptor: DescriptorInput<IEnumDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.Enum;
     }
 
     interface Enum {
@@ -56,7 +57,7 @@ declare module ".." {
 
     namespace OneOf {
         /** Creates a oneof from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IOneofDescriptorProto>): $protobuf.OneOf;
+        function fromDescriptor(descriptor: DescriptorInput<IOneofDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.OneOf;
     }
 
     interface OneOf {
@@ -66,7 +67,7 @@ declare module ".." {
 
     namespace Service {
         /** Creates a service from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IServiceDescriptorProto>, edition?: string, nested?: boolean): $protobuf.Service;
+        function fromDescriptor(descriptor: DescriptorInput<IServiceDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.Service;
     }
 
     interface Service {
@@ -76,7 +77,7 @@ declare module ".." {
 
     namespace Method {
         /** Creates a method from a descriptor. */
-        function fromDescriptor(descriptor: DescriptorInput<IMethodDescriptorProto>): $protobuf.Method;
+        function fromDescriptor(descriptor: DescriptorInput<IMethodDescriptorProto>, editionOrContext?: string | IDescriptorContext): $protobuf.Method;
     }
 
     interface Method {

package/ext/descriptor.generated.d.ts

@@ -170,6 +170,19 @@ export interface IFileOptions {
 /** Values of he FileOptions.OptimizeMode enum. */
 export type IFileOptionsOptimizeMode = number;
 
+/** Descriptor context. */
+export interface IDescriptorContext {
+
+    /** Syntax or edition to use for direct object descriptor imports */
+    edition?: string;
+
+    /** File-level features to apply for direct object descriptor imports */
+    features?: IFeatureSet;
+
+    /** Uses proto field names as reflected field names */
+    keepCase?: boolean;
+}
+
 /** Properties of a DescriptorProto message. */
 export interface IDescriptorProto {
 
@@ -258,8 +271,8 @@ export interface IFieldDescriptorProto {
     /** Oneof index if part of a oneof */
     oneofIndex?: number;
 
-    /** Not supported */
-    jsonName?: any;
+    /** JSON name (lowerCamelCase) */
+    jsonName?: string;
 
     /** Field options */
     options?: IFieldOptions;
@@ -398,12 +411,7 @@ export interface IMethodDescriptorProto {
     serverStreaming?: boolean;
 }
 
-/**
- * Properties of a MethodOptions message.
- *
- * Warning: this is not safe to use with editions protos, since it discards relevant file context.
- *
- */
+/** Properties of a MethodOptions message. */
 export interface IMethodOptions {
     deprecated?: boolean;
 }