From b0b5da5fd1e859cc59fab6fdfbfc46e58dde087e Mon Sep 17 00:00:00 2001 From: Timo Stamm Date: Wed, 18 Sep 2024 17:03:44 +0200 Subject: [PATCH] Generate full JSDoc for JSON types --- MANUAL.md | 4 +- .../js,json_types/extra/json_types_pb.d.ts | 4 +- .../gen/ts,json_types/extra/json_types_pb.ts | 4 +- .../src/wkt/gen/google/protobuf/any_pb.ts | 91 ++- .../src/wkt/gen/google/protobuf/api_pb.ts | 151 +++- .../gen/google/protobuf/compiler/plugin_pb.ts | 133 ++- .../wkt/gen/google/protobuf/descriptor_pb.ts | 771 ++++++++++++++++-- .../wkt/gen/google/protobuf/duration_pb.ts | 62 +- .../src/wkt/gen/google/protobuf/empty_pb.ts | 11 +- .../wkt/gen/google/protobuf/field_mask_pb.ts | 202 ++++- .../gen/google/protobuf/source_context_pb.ts | 8 +- .../src/wkt/gen/google/protobuf/struct_pb.ts | 33 +- .../wkt/gen/google/protobuf/timestamp_pb.ts | 93 ++- .../src/wkt/gen/google/protobuf/type_pb.ts | 97 ++- .../wkt/gen/google/protobuf/wrappers_pb.ts | 54 +- .../protoc-gen-es/src/protoc-gen-es-plugin.ts | 9 +- 16 files changed, 1627 insertions(+), 100 deletions(-) diff --git a/MANUAL.md b/MANUAL.md index 3c6fe8606..6b5649f64 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -1259,7 +1259,7 @@ the following additional export is generated: ```ts /** - * JSON type for the message Example. + * @generated from message Example */ export type ExampleJson = { /** @@ -1300,7 +1300,7 @@ enum Format { ```ts /** - * JSON type for the enum Format. + * @generated from enum Format */ export type FormatJson = "FORMAT_UNSPECIFIED" | "FORMAT_BINARY" | "FORMAT_JSON"; ``` diff --git a/packages/protobuf-test/src/gen/js,json_types/extra/json_types_pb.d.ts b/packages/protobuf-test/src/gen/js,json_types/extra/json_types_pb.d.ts index a532fd83b..c0c989068 100644 --- a/packages/protobuf-test/src/gen/js,json_types/extra/json_types_pb.d.ts +++ b/packages/protobuf-test/src/gen/js,json_types/extra/json_types_pb.d.ts @@ -161,7 +161,7 @@ export declare type JsonTypesMessage = Message<"spec.JsonTypesMessage"> & { }; /** - * JSON type for the message spec.JsonTypesMessage. + * @generated from message spec.JsonTypesMessage */ export declare type JsonTypesMessageJson = { /** @@ -322,7 +322,7 @@ export enum JsonTypeEnum { } /** - * JSON type for the enum spec.JsonTypeEnum. + * @generated from enum spec.JsonTypeEnum */ export declare type JsonTypeEnumJson = "JSON_TYPE_ENUM_UNSPECIFIED" | "JSON_TYPE_ENUM_YES" | "JSON_TYPE_ENUM_NO"; diff --git a/packages/protobuf-test/src/gen/ts,json_types/extra/json_types_pb.ts b/packages/protobuf-test/src/gen/ts,json_types/extra/json_types_pb.ts index 936f25743..35bfcc2d5 100644 --- a/packages/protobuf-test/src/gen/ts,json_types/extra/json_types_pb.ts +++ b/packages/protobuf-test/src/gen/ts,json_types/extra/json_types_pb.ts @@ -164,7 +164,7 @@ export type JsonTypesMessage = Message<"spec.JsonTypesMessage"> & { }; /** - * JSON type for the message spec.JsonTypesMessage. + * @generated from message spec.JsonTypesMessage */ export type JsonTypesMessageJson = { /** @@ -326,7 +326,7 @@ export enum JsonTypeEnum { } /** - * JSON type for the enum spec.JsonTypeEnum. + * @generated from enum spec.JsonTypeEnum */ export type JsonTypeEnumJson = "JSON_TYPE_ENUM_UNSPECIFIED" | "JSON_TYPE_ENUM_YES" | "JSON_TYPE_ENUM_NO"; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/any_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/any_pb.ts index 183358383..36b639676 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/any_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/any_pb.ts @@ -162,10 +162,97 @@ export type Any = Message<"google.protobuf.Any"> & { }; /** - * JSON type for the message google.protobuf.Any. + * `Any` contains an arbitrary serialized protocol buffer message along with a + * URL that describes the type of the serialized message. + * + * Protobuf library provides support to pack/unpack Any values in the form + * of utility functions or additional generated methods of the Any type. + * + * Example 1: Pack and unpack a message in C++. + * + * Foo foo = ...; + * Any any; + * any.PackFrom(foo); + * ... + * if (any.UnpackTo(&foo)) { + * ... + * } + * + * Example 2: Pack and unpack a message in Java. + * + * Foo foo = ...; + * Any any = Any.pack(foo); + * ... + * if (any.is(Foo.class)) { + * foo = any.unpack(Foo.class); + * } + * // or ... + * if (any.isSameTypeAs(Foo.getDefaultInstance())) { + * foo = any.unpack(Foo.getDefaultInstance()); + * } + * + * Example 3: Pack and unpack a message in Python. + * + * foo = Foo(...) + * any = Any() + * any.Pack(foo) + * ... + * if any.Is(Foo.DESCRIPTOR): + * any.Unpack(foo) + * ... + * + * Example 4: Pack and unpack a message in Go + * + * foo := &pb.Foo{...} + * any, err := anypb.New(foo) + * if err != nil { + * ... + * } + * ... + * foo := &pb.Foo{} + * if err := any.UnmarshalTo(foo); err != nil { + * ... + * } + * + * The pack methods provided by protobuf library will by default use + * 'type.googleapis.com/full.type.name' as the type URL and the unpack + * methods only use the fully qualified type name after the last '/' + * in the type URL, for example "foo.bar.com/x/y.z" will yield type + * name "y.z". + * + * JSON + * ==== + * The JSON representation of an `Any` value uses the regular + * representation of the deserialized, embedded message, with an + * additional field `@type` which contains the type URL. Example: + * + * package google.profile; + * message Person { + * string first_name = 1; + * string last_name = 2; + * } + * + * { + * "@type": "type.googleapis.com/google.profile.Person", + * "firstName": , + * "lastName": + * } + * + * If the embedded message type is well-known and has a custom JSON + * representation, that representation will be embedded adding a field + * `value` which holds the custom JSON in addition to the `@type` + * field. Example (for message [google.protobuf.Duration][]): + * + * { + * "@type": "type.googleapis.com/google.protobuf.Duration", + * "value": "1.212s" + * } + * + * + * @generated from message google.protobuf.Any */ export type AnyJson = { - "@type"?: string + "@type"?: string; }; /** diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/api_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/api_pb.ts index d4f796be7..a9459b755 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/api_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/api_pb.ts @@ -117,40 +117,85 @@ export type Api = Message<"google.protobuf.Api"> & { }; /** - * JSON type for the message google.protobuf.Api. + * Api is a light-weight descriptor for an API Interface. + * + * Interfaces are also described as "protocol buffer services" in some contexts, + * such as by the "service" keyword in a .proto file, but they are different + * from API Services, which represent a concrete implementation of an interface + * as opposed to simply a description of methods and bindings. They are also + * sometimes simply referred to as "APIs" in other contexts, such as the name of + * this message itself. See https://cloud.google.com/apis/design/glossary for + * detailed terminology. + * + * @generated from message google.protobuf.Api */ export type ApiJson = { /** + * The fully qualified name of this interface, including package name + * followed by the interface's simple name. + * * @generated from field: string name = 1; */ name?: string; /** + * The methods of this interface, in unspecified order. + * * @generated from field: repeated google.protobuf.Method methods = 2; */ methods?: MethodJson[]; /** + * Any metadata attached to the interface. + * * @generated from field: repeated google.protobuf.Option options = 3; */ options?: OptionJson[]; /** + * A version string for this interface. If specified, must have the form + * `major-version.minor-version`, as in `1.10`. If the minor version is + * omitted, it defaults to zero. If the entire version field is empty, the + * major version is derived from the package name, as outlined below. If the + * field is not empty, the version in the package name will be verified to be + * consistent with what is provided here. + * + * The versioning schema uses [semantic + * versioning](http://semver.org) where the major version number + * indicates a breaking change and the minor version an additive, + * non-breaking change. Both version numbers are signals to users + * what to expect from different versions, and should be carefully + * chosen based on the product plan. + * + * The major version is also reflected in the package name of the + * interface, which must end in `v`, as in + * `google.feature.v1`. For major versions 0 and 1, the suffix can + * be omitted. Zero major versions must only be used for + * experimental, non-GA interfaces. + * + * * @generated from field: string version = 4; */ version?: string; /** + * Source context for the protocol buffer service represented by this + * message. + * * @generated from field: google.protobuf.SourceContext source_context = 5; */ sourceContext?: SourceContextJson; /** + * Included interfaces. See [Mixin][]. + * * @generated from field: repeated google.protobuf.Mixin mixins = 6; */ mixins?: MixinJson[]; /** + * The source syntax of the service. + * * @generated from field: google.protobuf.Syntax syntax = 7; */ syntax?: SyntaxJson; @@ -220,40 +265,56 @@ export type Method = Message<"google.protobuf.Method"> & { }; /** - * JSON type for the message google.protobuf.Method. + * Method represents a method of an API interface. + * + * @generated from message google.protobuf.Method */ export type MethodJson = { /** + * The simple name of this method. + * * @generated from field: string name = 1; */ name?: string; /** + * A URL of the input message type. + * * @generated from field: string request_type_url = 2; */ requestTypeUrl?: string; /** + * If true, the request is streamed. + * * @generated from field: bool request_streaming = 3; */ requestStreaming?: boolean; /** + * The URL of the output message type. + * * @generated from field: string response_type_url = 4; */ responseTypeUrl?: string; /** + * If true, the response is streamed. + * * @generated from field: bool response_streaming = 5; */ responseStreaming?: boolean; /** + * Any metadata attached to the method. + * * @generated from field: repeated google.protobuf.Option options = 6; */ options?: OptionJson[]; /** + * The source syntax of this method. + * * @generated from field: google.protobuf.Syntax syntax = 7; */ syntax?: SyntaxJson; @@ -366,15 +427,99 @@ export type Mixin = Message<"google.protobuf.Mixin"> & { }; /** - * JSON type for the message google.protobuf.Mixin. + * Declares an API Interface to be included in this interface. The including + * interface must redeclare all the methods from the included interface, but + * documentation and options are inherited as follows: + * + * - If after comment and whitespace stripping, the documentation + * string of the redeclared method is empty, it will be inherited + * from the original method. + * + * - Each annotation belonging to the service config (http, + * visibility) which is not set in the redeclared method will be + * inherited. + * + * - If an http annotation is inherited, the path pattern will be + * modified as follows. Any version prefix will be replaced by the + * version of the including interface plus the [root][] path if + * specified. + * + * Example of a simple mixin: + * + * package google.acl.v1; + * service AccessControl { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v1/{resource=**}:getAcl"; + * } + * } + * + * package google.storage.v2; + * service Storage { + * rpc GetAcl(GetAclRequest) returns (Acl); + * + * // Get a data record. + * rpc GetData(GetDataRequest) returns (Data) { + * option (google.api.http).get = "/v2/{resource=**}"; + * } + * } + * + * Example of a mixin configuration: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * + * The mixin construct implies that all methods in `AccessControl` are + * also declared with same name and request/response types in + * `Storage`. A documentation generator or annotation processor will + * see the effective `Storage.GetAcl` method after inherting + * documentation and annotations as follows: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/{resource=**}:getAcl"; + * } + * ... + * } + * + * Note how the version in the path pattern changed from `v1` to `v2`. + * + * If the `root` field in the mixin is specified, it should be a + * relative path under which inherited HTTP paths are placed. Example: + * + * apis: + * - name: google.storage.v2.Storage + * mixins: + * - name: google.acl.v1.AccessControl + * root: acls + * + * This implies the following inherited HTTP annotation: + * + * service Storage { + * // Get the underlying ACL object. + * rpc GetAcl(GetAclRequest) returns (Acl) { + * option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; + * } + * ... + * } + * + * @generated from message google.protobuf.Mixin */ export type MixinJson = { /** + * The fully qualified name of the interface which is included. + * * @generated from field: string name = 1; */ name?: string; /** + * If non-empty specifies a path under which inherited HTTP paths + * are rooted. + * * @generated from field: string root = 2; */ root?: string; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/compiler/plugin_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/compiler/plugin_pb.ts index 28c3a27b4..bf1cfc923 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/compiler/plugin_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/compiler/plugin_pb.ts @@ -74,7 +74,9 @@ export type Version = Message<"google.protobuf.compiler.Version"> & { }; /** - * JSON type for the message google.protobuf.compiler.Version. + * The version number of protocol compiler. + * + * @generated from message google.protobuf.compiler.Version */ export type VersionJson = { /** @@ -93,6 +95,9 @@ export type VersionJson = { patch?: number; /** + * A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should + * be empty for mainline stable releases. + * * @generated from field: optional string suffix = 4; */ suffix?: string; @@ -170,30 +175,64 @@ export type CodeGeneratorRequest = Message<"google.protobuf.compiler.CodeGenerat }; /** - * JSON type for the message google.protobuf.compiler.CodeGeneratorRequest. + * An encoded CodeGeneratorRequest is written to the plugin's stdin. + * + * @generated from message google.protobuf.compiler.CodeGeneratorRequest */ export type CodeGeneratorRequestJson = { /** + * The .proto files that were explicitly listed on the command-line. The + * code generator should generate code only for these files. Each file's + * descriptor will be included in proto_file, below. + * * @generated from field: repeated string file_to_generate = 1; */ fileToGenerate?: string[]; /** + * The generator parameter passed on the command-line. + * * @generated from field: optional string parameter = 2; */ parameter?: string; /** + * FileDescriptorProtos for all files in files_to_generate and everything + * they import. The files will appear in topological order, so each file + * appears before any file that imports it. + * + * Note: the files listed in files_to_generate will include runtime-retention + * options only, but all other files will include source-retention options. + * The source_file_descriptors field below is available in case you need + * source-retention options for files_to_generate. + * + * protoc guarantees that all proto_files will be written after + * the fields above, even though this is not technically guaranteed by the + * protobuf wire format. This theoretically could allow a plugin to stream + * in the FileDescriptorProtos and handle them one by one rather than read + * the entire set into memory at once. However, as of this writing, this + * is not similarly optimized on protoc's end -- it will store all fields in + * memory at once before sending them to the plugin. + * + * Type names of fields and extensions in the FileDescriptorProto are always + * fully qualified. + * * @generated from field: repeated google.protobuf.FileDescriptorProto proto_file = 15; */ protoFile?: FileDescriptorProtoJson[]; /** + * File descriptors with all options, including source-retention options. + * These descriptors are only provided for the files listed in + * files_to_generate. + * * @generated from field: repeated google.protobuf.FileDescriptorProto source_file_descriptors = 17; */ sourceFileDescriptors?: FileDescriptorProtoJson[]; /** + * The version number of protocol compiler. + * * @generated from field: optional google.protobuf.compiler.Version compiler_version = 3; */ compilerVersion?: VersionJson; @@ -261,25 +300,49 @@ export type CodeGeneratorResponse = Message<"google.protobuf.compiler.CodeGenera }; /** - * JSON type for the message google.protobuf.compiler.CodeGeneratorResponse. + * The plugin writes an encoded CodeGeneratorResponse to stdout. + * + * @generated from message google.protobuf.compiler.CodeGeneratorResponse */ export type CodeGeneratorResponseJson = { /** + * Error message. If non-empty, code generation failed. The plugin process + * should exit with status code zero even if it reports an error in this way. + * + * This should be used to indicate errors in .proto files which prevent the + * code generator from generating correct code. Errors which indicate a + * problem in protoc itself -- such as the input CodeGeneratorRequest being + * unparseable -- should be reported by writing a message to stderr and + * exiting with a non-zero status code. + * * @generated from field: optional string error = 1; */ error?: string; /** + * A bitmask of supported features that the code generator supports. + * This is a bitwise "or" of values from the Feature enum. + * * @generated from field: optional uint64 supported_features = 2; */ supportedFeatures?: string; /** + * The minimum edition this plugin supports. This will be treated as an + * Edition enum, but we want to allow unknown values. It should be specified + * according the edition enum value, *not* the edition number. Only takes + * effect for plugins that have FEATURE_SUPPORTS_EDITIONS set. + * * @generated from field: optional int32 minimum_edition = 3; */ minimumEdition?: number; /** + * The maximum edition this plugin supports. This will be treated as an + * Edition enum, but we want to allow unknown values. It should be specified + * according the edition enum value, *not* the edition number. Only takes + * effect for plugins that have FEATURE_SUPPORTS_EDITIONS set. + * * @generated from field: optional int32 maximum_edition = 4; */ maximumEdition?: number; @@ -381,25 +444,83 @@ export type CodeGeneratorResponse_File = Message<"google.protobuf.compiler.CodeG }; /** - * JSON type for the message google.protobuf.compiler.CodeGeneratorResponse.File. + * Represents a single generated file. + * + * @generated from message google.protobuf.compiler.CodeGeneratorResponse.File */ export type CodeGeneratorResponse_FileJson = { /** + * The file name, relative to the output directory. The name must not + * contain "." or ".." components and must be relative, not be absolute (so, + * the file cannot lie outside the output directory). "/" must be used as + * the path separator, not "\". + * + * If the name is omitted, the content will be appended to the previous + * file. This allows the generator to break large files into small chunks, + * and allows the generated text to be streamed back to protoc so that large + * files need not reside completely in memory at one time. Note that as of + * this writing protoc does not optimize for this -- it will read the entire + * CodeGeneratorResponse before writing files to disk. + * * @generated from field: optional string name = 1; */ name?: string; /** + * If non-empty, indicates that the named file should already exist, and the + * content here is to be inserted into that file at a defined insertion + * point. This feature allows a code generator to extend the output + * produced by another code generator. The original generator may provide + * insertion points by placing special annotations in the file that look + * like: + * @@protoc_insertion_point(NAME) + * The annotation can have arbitrary text before and after it on the line, + * which allows it to be placed in a comment. NAME should be replaced with + * an identifier naming the point -- this is what other generators will use + * as the insertion_point. Code inserted at this point will be placed + * immediately above the line containing the insertion point (thus multiple + * insertions to the same point will come out in the order they were added). + * The double-@ is intended to make it unlikely that the generated code + * could contain things that look like insertion points by accident. + * + * For example, the C++ code generator places the following line in the + * .pb.h files that it generates: + * // @@protoc_insertion_point(namespace_scope) + * This line appears within the scope of the file's package namespace, but + * outside of any particular class. Another plugin can then specify the + * insertion_point "namespace_scope" to generate additional classes or + * other declarations that should be placed in this scope. + * + * Note that if the line containing the insertion point begins with + * whitespace, the same whitespace will be added to every line of the + * inserted text. This is useful for languages like Python, where + * indentation matters. In these languages, the insertion point comment + * should be indented the same amount as any inserted code will need to be + * in order to work correctly in that context. + * + * The code generator that generates the initial file and the one which + * inserts into it must both run as part of a single invocation of protoc. + * Code generators are executed in the order in which they appear on the + * command line. + * + * If |insertion_point| is present, |name| must also be present. + * * @generated from field: optional string insertion_point = 2; */ insertionPoint?: string; /** + * The file contents. + * * @generated from field: optional string content = 15; */ content?: string; /** + * Information describing the file content being inserted. If an insertion + * point is used, this information will be appropriately offset and inserted + * into the code generation metadata for the generated files. + * * @generated from field: optional google.protobuf.GeneratedCodeInfo generated_code_info = 16; */ generatedCodeInfo?: GeneratedCodeInfoJson; @@ -435,7 +556,9 @@ export enum CodeGeneratorResponse_Feature { } /** - * JSON type for the enum google.protobuf.compiler.CodeGeneratorResponse.Feature. + * Sync with code_generator.h. + * + * @generated from enum google.protobuf.compiler.CodeGeneratorResponse.Feature */ export type CodeGeneratorResponse_FeatureJson = "FEATURE_NONE" | "FEATURE_PROTO3_OPTIONAL" | "FEATURE_SUPPORTS_EDITIONS"; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/descriptor_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/descriptor_pb.ts index 516190417..5e3ad2a3b 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/descriptor_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/descriptor_pb.ts @@ -50,7 +50,10 @@ export type FileDescriptorSet = Message<"google.protobuf.FileDescriptorSet"> & { }; /** - * JSON type for the message google.protobuf.FileDescriptorSet. + * The protocol compiler can output a FileDescriptorSet containing the .proto + * files it parses. + * + * @generated from message google.protobuf.FileDescriptorSet */ export type FileDescriptorSetJson = { /** @@ -164,35 +167,50 @@ export type FileDescriptorProto = Message<"google.protobuf.FileDescriptorProto"> }; /** - * JSON type for the message google.protobuf.FileDescriptorProto. + * Describes a complete .proto file. + * + * @generated from message google.protobuf.FileDescriptorProto */ export type FileDescriptorProtoJson = { /** + * file name, relative to root of source tree + * * @generated from field: optional string name = 1; */ name?: string; /** + * e.g. "foo", "foo.bar", etc. + * * @generated from field: optional string package = 2; */ package?: string; /** + * Names of files imported by this file. + * * @generated from field: repeated string dependency = 3; */ dependency?: string[]; /** + * Indexes of the public imported files in the dependency list above. + * * @generated from field: repeated int32 public_dependency = 10; */ publicDependency?: number[]; /** + * Indexes of the weak imported files in the dependency list. + * For Google-internal migration only. Do not use. + * * @generated from field: repeated int32 weak_dependency = 11; */ weakDependency?: number[]; /** + * All top-level definitions in this file. + * * @generated from field: repeated google.protobuf.DescriptorProto message_type = 4; */ messageType?: DescriptorProtoJson[]; @@ -218,16 +236,28 @@ export type FileDescriptorProtoJson = { options?: FileOptionsJson; /** + * This field contains optional information about the original source code. + * You may safely remove this entire field without harming runtime + * functionality of the descriptors -- the information is needed only by + * development tools. + * * @generated from field: optional google.protobuf.SourceCodeInfo source_code_info = 9; */ sourceCodeInfo?: SourceCodeInfoJson; /** + * The syntax of the proto file. + * The supported values are "proto2", "proto3", and "editions". + * + * If `edition` is present, this value must be "editions". + * * @generated from field: optional string syntax = 12; */ syntax?: string; /** + * The edition of the proto file. + * * @generated from field: optional google.protobuf.Edition edition = 14; */ edition?: EditionJson; @@ -301,7 +331,9 @@ export type DescriptorProto = Message<"google.protobuf.DescriptorProto"> & { }; /** - * JSON type for the message google.protobuf.DescriptorProto. + * Describes a message type. + * + * @generated from message google.protobuf.DescriptorProto */ export type DescriptorProtoJson = { /** @@ -350,6 +382,9 @@ export type DescriptorProtoJson = { reservedRange?: DescriptorProto_ReservedRangeJson[]; /** + * Reserved field names, which may not be used by fields in the same message. + * A given name may only be reserved once. + * * @generated from field: repeated string reserved_name = 10; */ reservedName?: string[]; @@ -387,15 +422,19 @@ export type DescriptorProto_ExtensionRange = Message<"google.protobuf.Descriptor }; /** - * JSON type for the message google.protobuf.DescriptorProto.ExtensionRange. + * @generated from message google.protobuf.DescriptorProto.ExtensionRange */ export type DescriptorProto_ExtensionRangeJson = { /** + * Inclusive. + * * @generated from field: optional int32 start = 1; */ start?: number; /** + * Exclusive. + * * @generated from field: optional int32 end = 2; */ end?: number; @@ -437,15 +476,23 @@ export type DescriptorProto_ReservedRange = Message<"google.protobuf.DescriptorP }; /** - * JSON type for the message google.protobuf.DescriptorProto.ReservedRange. + * Range of reserved tag numbers. Reserved tag numbers may not be used by + * fields or extension ranges in the same message. Reserved ranges may + * not overlap. + * + * @generated from message google.protobuf.DescriptorProto.ReservedRange */ export type DescriptorProto_ReservedRangeJson = { /** + * Inclusive. + * * @generated from field: optional int32 start = 1; */ start?: number; /** + * Exclusive. + * * @generated from field: optional int32 end = 2; */ end?: number; @@ -496,25 +543,37 @@ export type ExtensionRangeOptions = Message<"google.protobuf.ExtensionRangeOptio }; /** - * JSON type for the message google.protobuf.ExtensionRangeOptions. + * @generated from message google.protobuf.ExtensionRangeOptions */ export type ExtensionRangeOptionsJson = { /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; /** + * For external users: DO NOT USE. We are in the process of open sourcing + * extension declaration and executing internal cleanups before it can be + * used externally. + * * @generated from field: repeated google.protobuf.ExtensionRangeOptions.Declaration declaration = 2; */ declaration?: ExtensionRangeOptions_DeclarationJson[]; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 50; */ features?: FeatureSetJson; /** + * The verification state of the range. + * TODO: flip the default to DECLARATION once all empty ranges + * are marked as UNVERIFIED. + * * @generated from field: optional google.protobuf.ExtensionRangeOptions.VerificationState verification = 3 [default = UNVERIFIED]; */ verification?: ExtensionRangeOptions_VerificationStateJson; @@ -574,30 +633,46 @@ export type ExtensionRangeOptions_Declaration = Message<"google.protobuf.Extensi }; /** - * JSON type for the message google.protobuf.ExtensionRangeOptions.Declaration. + * @generated from message google.protobuf.ExtensionRangeOptions.Declaration */ export type ExtensionRangeOptions_DeclarationJson = { /** + * The extension number declared within the extension range. + * * @generated from field: optional int32 number = 1; */ number?: number; /** + * The fully-qualified name of the extension field. There must be a leading + * dot in front of the full name. + * * @generated from field: optional string full_name = 2; */ fullName?: string; /** + * The fully-qualified type name of the extension field. Unlike + * Metadata.type, Declaration.type must have a leading dot for messages + * and enums. + * * @generated from field: optional string type = 3; */ type?: string; /** + * If true, indicates that the number is reserved in the extension range, + * and any extension field with the number will fail to compile. Set this + * when a declared extension field is deleted. + * * @generated from field: optional bool reserved = 5; */ reserved?: boolean; /** + * If true, indicates that the extension must be defined as repeated. + * Otherwise the extension must be defined as optional. + * * @generated from field: optional bool repeated = 6; */ repeated?: boolean; @@ -630,7 +705,9 @@ export enum ExtensionRangeOptions_VerificationState { } /** - * JSON type for the enum google.protobuf.ExtensionRangeOptions.VerificationState. + * The verification state of the extension range. + * + * @generated from enum google.protobuf.ExtensionRangeOptions.VerificationState */ export type ExtensionRangeOptions_VerificationStateJson = "DECLARATION" | "UNVERIFIED"; @@ -750,7 +827,9 @@ export type FieldDescriptorProto = Message<"google.protobuf.FieldDescriptorProto }; /** - * JSON type for the message google.protobuf.FieldDescriptorProto. + * Describes a field within a message. + * + * @generated from message google.protobuf.FieldDescriptorProto */ export type FieldDescriptorProtoJson = { /** @@ -769,31 +848,56 @@ export type FieldDescriptorProtoJson = { label?: FieldDescriptorProto_LabelJson; /** + * If type_name is set, this need not be set. If both this and type_name + * are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. + * * @generated from field: optional google.protobuf.FieldDescriptorProto.Type type = 5; */ type?: FieldDescriptorProto_TypeJson; /** + * For message and enum types, this is the name of the type. If the name + * starts with a '.', it is fully-qualified. Otherwise, C++-like scoping + * rules are used to find the type (i.e. first the nested types within this + * message are searched, then within the parent, on up to the root + * namespace). + * * @generated from field: optional string type_name = 6; */ typeName?: string; /** + * For extensions, this is the name of the type being extended. It is + * resolved in the same manner as type_name. + * * @generated from field: optional string extendee = 2; */ extendee?: string; /** + * For numeric types, contains the original text representation of the value. + * For booleans, "true" or "false". + * For strings, contains the default text contents (not escaped in any way). + * For bytes, contains the C escaped value. All bytes >= 128 are escaped. + * * @generated from field: optional string default_value = 7; */ defaultValue?: string; /** + * If set, gives the index of a oneof in the containing type's oneof_decl + * list. This field is a member of that oneof. + * * @generated from field: optional int32 oneof_index = 9; */ oneofIndex?: number; /** + * JSON name of this field. The value is set by protocol compiler. If the + * user has set a "json_name" option on this field, that option's value + * will be used. Otherwise, it's deduced from the field's name by converting + * it to camelCase. + * * @generated from field: optional string json_name = 10; */ jsonName?: string; @@ -804,6 +908,28 @@ export type FieldDescriptorProtoJson = { options?: FieldOptionsJson; /** + * If true, this is a proto3 "optional". When a proto3 field is optional, it + * tracks presence regardless of field type. + * + * When proto3_optional is true, this field must belong to a oneof to signal + * to old proto3 clients that presence is tracked for this field. This oneof + * is known as a "synthetic" oneof, and this field must be its sole member + * (each proto3 optional field gets its own synthetic oneof). Synthetic oneofs + * exist in the descriptor only, and do not generate any API. Synthetic oneofs + * must be ordered after all "real" oneofs. + * + * For message fields, proto3_optional doesn't create any semantic change, + * since non-repeated message fields always track presence. However it still + * indicates the semantic detail of whether the user wrote "optional" or not. + * This can be useful for round-tripping the .proto file. For consistency we + * give message fields a synthetic oneof also, even though it is not required + * to track presence. This is especially important because the parser can't + * tell if a field is a message or an enum, so it must always create a + * synthetic oneof. + * + * Proto2 optional fields do not set this flag, because they already indicate + * optional with `LABEL_OPTIONAL`. + * * @generated from field: optional bool proto3_optional = 17; */ proto3Optional?: boolean; @@ -935,7 +1061,7 @@ export enum FieldDescriptorProto_Type { } /** - * JSON type for the enum google.protobuf.FieldDescriptorProto.Type. + * @generated from enum google.protobuf.FieldDescriptorProto.Type */ export type FieldDescriptorProto_TypeJson = "TYPE_DOUBLE" | "TYPE_FLOAT" | "TYPE_INT64" | "TYPE_UINT64" | "TYPE_INT32" | "TYPE_FIXED64" | "TYPE_FIXED32" | "TYPE_BOOL" | "TYPE_STRING" | "TYPE_GROUP" | "TYPE_MESSAGE" | "TYPE_BYTES" | "TYPE_UINT32" | "TYPE_ENUM" | "TYPE_SFIXED32" | "TYPE_SFIXED64" | "TYPE_SINT32" | "TYPE_SINT64"; @@ -972,7 +1098,7 @@ export enum FieldDescriptorProto_Label { } /** - * JSON type for the enum google.protobuf.FieldDescriptorProto.Label. + * @generated from enum google.protobuf.FieldDescriptorProto.Label */ export type FieldDescriptorProto_LabelJson = "LABEL_OPTIONAL" | "LABEL_REPEATED" | "LABEL_REQUIRED"; @@ -1000,7 +1126,9 @@ export type OneofDescriptorProto = Message<"google.protobuf.OneofDescriptorProto }; /** - * JSON type for the message google.protobuf.OneofDescriptorProto. + * Describes a oneof. + * + * @generated from message google.protobuf.OneofDescriptorProto */ export type OneofDescriptorProtoJson = { /** @@ -1061,7 +1189,9 @@ export type EnumDescriptorProto = Message<"google.protobuf.EnumDescriptorProto"> }; /** - * JSON type for the message google.protobuf.EnumDescriptorProto. + * Describes an enum type. + * + * @generated from message google.protobuf.EnumDescriptorProto */ export type EnumDescriptorProtoJson = { /** @@ -1080,11 +1210,18 @@ export type EnumDescriptorProtoJson = { options?: EnumOptionsJson; /** + * Range of reserved numeric values. Reserved numeric values may not be used + * by enum values in the same enum declaration. Reserved ranges may not + * overlap. + * * @generated from field: repeated google.protobuf.EnumDescriptorProto.EnumReservedRange reserved_range = 4; */ reservedRange?: EnumDescriptorProto_EnumReservedRangeJson[]; /** + * Reserved enum value names, which may not be reused. A given name may only + * be reserved once. + * * @generated from field: repeated string reserved_name = 5; */ reservedName?: string[]; @@ -1124,15 +1261,26 @@ export type EnumDescriptorProto_EnumReservedRange = Message<"google.protobuf.Enu }; /** - * JSON type for the message google.protobuf.EnumDescriptorProto.EnumReservedRange. + * Range of reserved numeric values. Reserved values may not be used by + * entries in the same enum. Reserved ranges may not overlap. + * + * Note that this is distinct from DescriptorProto.ReservedRange in that it + * is inclusive such that it can appropriately represent the entire int32 + * domain. + * + * @generated from message google.protobuf.EnumDescriptorProto.EnumReservedRange */ export type EnumDescriptorProto_EnumReservedRangeJson = { /** + * Inclusive. + * * @generated from field: optional int32 start = 1; */ start?: number; /** + * Inclusive. + * * @generated from field: optional int32 end = 2; */ end?: number; @@ -1168,7 +1316,9 @@ export type EnumValueDescriptorProto = Message<"google.protobuf.EnumValueDescrip }; /** - * JSON type for the message google.protobuf.EnumValueDescriptorProto. + * Describes a value within an enum. + * + * @generated from message google.protobuf.EnumValueDescriptorProto */ export type EnumValueDescriptorProtoJson = { /** @@ -1217,7 +1367,9 @@ export type ServiceDescriptorProto = Message<"google.protobuf.ServiceDescriptorP }; /** - * JSON type for the message google.protobuf.ServiceDescriptorProto. + * Describes a service. + * + * @generated from message google.protobuf.ServiceDescriptorProto */ export type ServiceDescriptorProtoJson = { /** @@ -1288,7 +1440,9 @@ export type MethodDescriptorProto = Message<"google.protobuf.MethodDescriptorPro }; /** - * JSON type for the message google.protobuf.MethodDescriptorProto. + * Describes a method of a service. + * + * @generated from message google.protobuf.MethodDescriptorProto */ export type MethodDescriptorProtoJson = { /** @@ -1297,6 +1451,9 @@ export type MethodDescriptorProtoJson = { name?: string; /** + * Input and output type names. These are resolved in the same way as + * FieldDescriptorProto.type_name, but must refer to a message type. + * * @generated from field: optional string input_type = 2; */ inputType?: string; @@ -1312,11 +1469,15 @@ export type MethodDescriptorProtoJson = { options?: MethodOptionsJson; /** + * Identifies if client streams multiple client messages + * * @generated from field: optional bool client_streaming = 5 [default = false]; */ clientStreaming?: boolean; /** + * Identifies if server streams multiple server messages + * * @generated from field: optional bool server_streaming = 6 [default = false]; */ serverStreaming?: boolean; @@ -1527,30 +1688,62 @@ export type FileOptions = Message<"google.protobuf.FileOptions"> & { }; /** - * JSON type for the message google.protobuf.FileOptions. + * @generated from message google.protobuf.FileOptions */ export type FileOptionsJson = { /** + * Sets the Java package where classes generated from this .proto will be + * placed. By default, the proto package is used, but this is often + * inappropriate because proto packages do not normally start with backwards + * domain names. + * * @generated from field: optional string java_package = 1; */ javaPackage?: string; /** + * Controls the name of the wrapper Java class generated for the .proto file. + * That class will always contain the .proto file's getDescriptor() method as + * well as any top-level extensions defined in the .proto file. + * If java_multiple_files is disabled, then all the other classes from the + * .proto file will be nested inside the single wrapper outer class. + * * @generated from field: optional string java_outer_classname = 8; */ javaOuterClassname?: string; /** + * If enabled, then the Java code generator will generate a separate .java + * file for each top-level message, enum, and service defined in the .proto + * file. Thus, these types will *not* be nested inside the wrapper class + * named by java_outer_classname. However, the wrapper class will still be + * generated to contain the file's getDescriptor() method as well as any + * top-level extensions defined in the file. + * * @generated from field: optional bool java_multiple_files = 10 [default = false]; */ javaMultipleFiles?: boolean; /** + * This option does nothing. + * * @generated from field: optional bool java_generate_equals_and_hash = 20 [deprecated = true]; + * @deprecated */ javaGenerateEqualsAndHash?: boolean; /** + * A proto2 file can set this to true to opt in to UTF-8 checking for Java, + * which will throw an exception if invalid UTF-8 is parsed from the wire or + * assigned to a string field. + * + * TODO: clarify exactly what kinds of field types this option + * applies to, and update these docs accordingly. + * + * Proto3 files already perform these checks. Setting the option explicitly to + * false has no effect: it cannot be used to opt proto3 files out of UTF-8 + * checks. + * * @generated from field: optional bool java_string_check_utf8 = 27 [default = false]; */ javaStringCheckUtf8?: boolean; @@ -1561,11 +1754,28 @@ export type FileOptionsJson = { optimizeFor?: FileOptions_OptimizeModeJson; /** + * Sets the Go package where structs generated from this .proto will be + * placed. If omitted, the Go package will be derived from the following: + * - The basename of the package import path, if provided. + * - Otherwise, the package statement in the .proto file, if present. + * - Otherwise, the basename of the .proto file, without extension. + * * @generated from field: optional string go_package = 11; */ goPackage?: string; /** + * Should generic services be generated in each language? "Generic" services + * are not specific to any particular RPC system. They are generated by the + * main code generators in each language (without additional plugins). + * Generic services were the only kind of service generation supported by + * early versions of google.protobuf. + * + * Generic services are now considered deprecated in favor of using plugins + * that generate code specific to your particular RPC system. Therefore, + * these default to false. Old code which depends on generic services should + * explicitly set them to true. + * * @generated from field: optional bool cc_generic_services = 16 [default = false]; */ ccGenericServices?: boolean; @@ -1581,56 +1791,94 @@ export type FileOptionsJson = { pyGenericServices?: boolean; /** + * Is this file deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for everything in the file, or it will be completely ignored; in the very + * least, this is a formalization for deprecating files. + * * @generated from field: optional bool deprecated = 23 [default = false]; */ deprecated?: boolean; /** + * Enables the use of arenas for the proto messages in this file. This applies + * only to generated classes for C++. + * * @generated from field: optional bool cc_enable_arenas = 31 [default = true]; */ ccEnableArenas?: boolean; /** + * Sets the objective c class prefix which is prepended to all objective c + * generated classes from this .proto. There is no default. + * * @generated from field: optional string objc_class_prefix = 36; */ objcClassPrefix?: string; /** + * Namespace for generated classes; defaults to the package. + * * @generated from field: optional string csharp_namespace = 37; */ csharpNamespace?: string; /** + * By default Swift generators will take the proto package and CamelCase it + * replacing '.' with underscore and use that to prefix the types/symbols + * defined. When this options is provided, they will use this value instead + * to prefix the types/symbols defined. + * * @generated from field: optional string swift_prefix = 39; */ swiftPrefix?: string; /** + * Sets the php class prefix which is prepended to all php generated classes + * from this .proto. Default is empty. + * * @generated from field: optional string php_class_prefix = 40; */ phpClassPrefix?: string; /** + * Use this option to change the namespace of php generated classes. Default + * is empty. When this option is empty, the package name will be used for + * determining the namespace. + * * @generated from field: optional string php_namespace = 41; */ phpNamespace?: string; /** - * @generated from field: optional string php_metadata_namespace = 44; - */ - phpMetadataNamespace?: string; + * Use this option to change the namespace of php generated metadata classes. + * Default is empty. When this option is empty, the proto file name will be + * used for determining the namespace. + * + * @generated from field: optional string php_metadata_namespace = 44; + */ + phpMetadataNamespace?: string; /** + * Use this option to change the package of ruby generated classes. Default + * is empty. When this option is not set, the package name will be used for + * determining the ruby package. + * * @generated from field: optional string ruby_package = 45; */ rubyPackage?: string; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 50; */ features?: FeatureSetJson; /** + * The parser stores options it doesn't recognize here. + * See the documentation for the "Options" section above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -1674,7 +1922,9 @@ export enum FileOptions_OptimizeMode { } /** - * JSON type for the enum google.protobuf.FileOptions.OptimizeMode. + * Generated classes can be optimized for speed or code size. + * + * @generated from enum google.protobuf.FileOptions.OptimizeMode */ export type FileOptions_OptimizeModeJson = "SPEED" | "CODE_SIZE" | "LITE_RUNTIME"; @@ -1791,40 +2041,106 @@ export type MessageOptions = Message<"google.protobuf.MessageOptions"> & { }; /** - * JSON type for the message google.protobuf.MessageOptions. + * @generated from message google.protobuf.MessageOptions */ export type MessageOptionsJson = { /** + * Set true to use the old proto1 MessageSet wire format for extensions. + * This is provided for backwards-compatibility with the MessageSet wire + * format. You should not use this for any other reason: It's less + * efficient, has fewer features, and is more complicated. + * + * The message must be defined exactly as follows: + * message Foo { + * option message_set_wire_format = true; + * extensions 4 to max; + * } + * Note that the message cannot have any defined fields; MessageSets only + * have extensions. + * + * All extensions of your type must be singular messages; e.g. they cannot + * be int32s, enums, or repeated messages. + * + * Because this is an option, the above two restrictions are not enforced by + * the protocol compiler. + * * @generated from field: optional bool message_set_wire_format = 1 [default = false]; */ messageSetWireFormat?: boolean; /** + * Disables the generation of the standard "descriptor()" accessor, which can + * conflict with a field of the same name. This is meant to make migration + * from proto1 easier; new code should avoid fields named "descriptor". + * * @generated from field: optional bool no_standard_descriptor_accessor = 2 [default = false]; */ noStandardDescriptorAccessor?: boolean; /** + * Is this message deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for the message, or it will be completely ignored; in the very least, + * this is a formalization for deprecating messages. + * * @generated from field: optional bool deprecated = 3 [default = false]; */ deprecated?: boolean; /** + * Whether the message is an automatically generated map entry type for the + * maps field. + * + * For maps fields: + * map map_field = 1; + * The parsed descriptor looks like: + * message MapFieldEntry { + * option map_entry = true; + * optional KeyType key = 1; + * optional ValueType value = 2; + * } + * repeated MapFieldEntry map_field = 1; + * + * Implementations may choose not to generate the map_entry=true message, but + * use a native map in the target language to hold the keys and values. + * The reflection APIs in such implementations still need to work as + * if the field is a repeated message field. + * + * NOTE: Do not set the option in .proto files. Always use the maps syntax + * instead. The option should only be implicitly set by the proto compiler + * parser. + * * @generated from field: optional bool map_entry = 7; */ mapEntry?: boolean; /** + * Enable the legacy handling of JSON field name conflicts. This lowercases + * and strips underscored from the fields before comparison in proto3 only. + * The new behavior takes `json_name` into account and applies to proto2 as + * well. + * + * This should only be used as a temporary measure against broken builds due + * to the change in behavior for JSON field name conflicts. + * + * TODO This is legacy behavior we plan to remove once downstream + * teams have had time to migrate. + * * @generated from field: optional bool deprecated_legacy_json_field_conflicts = 11 [deprecated = true]; + * @deprecated */ deprecatedLegacyJsonFieldConflicts?: boolean; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 12; */ features?: FeatureSetJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -1982,45 +2298,110 @@ export type FieldOptions = Message<"google.protobuf.FieldOptions"> & { }; /** - * JSON type for the message google.protobuf.FieldOptions. + * @generated from message google.protobuf.FieldOptions */ export type FieldOptionsJson = { /** + * NOTE: ctype is deprecated. Use `features.(pb.cpp).string_type` instead. + * The ctype option instructs the C++ code generator to use a different + * representation of the field than it normally would. See the specific + * options below. This option is only implemented to support use of + * [ctype=CORD] and [ctype=STRING] (the default) on non-repeated fields of + * type "bytes" in the open source release. + * TODO: make ctype actually deprecated. + * * @generated from field: optional google.protobuf.FieldOptions.CType ctype = 1 [default = STRING]; */ ctype?: FieldOptions_CTypeJson; /** + * The packed option can be enabled for repeated primitive fields to enable + * a more efficient representation on the wire. Rather than repeatedly + * writing the tag and type for each element, the entire array is encoded as + * a single length-delimited blob. In proto3, only explicit setting it to + * false will avoid using packed encoding. This option is prohibited in + * Editions, but the `repeated_field_encoding` feature can be used to control + * the behavior. + * * @generated from field: optional bool packed = 2; */ packed?: boolean; /** + * The jstype option determines the JavaScript type used for values of the + * field. The option is permitted only for 64 bit integral and fixed types + * (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING + * is represented as JavaScript string, which avoids loss of precision that + * can happen when a large value is converted to a floating point JavaScript. + * Specifying JS_NUMBER for the jstype causes the generated JavaScript code to + * use the JavaScript "number" type. The behavior of the default option + * JS_NORMAL is implementation dependent. + * + * This option is an enum to permit additional types to be added, e.g. + * goog.math.Integer. + * * @generated from field: optional google.protobuf.FieldOptions.JSType jstype = 6 [default = JS_NORMAL]; */ jstype?: FieldOptions_JSTypeJson; /** + * Should this field be parsed lazily? Lazy applies only to message-type + * fields. It means that when the outer message is initially parsed, the + * inner message's contents will not be parsed but instead stored in encoded + * form. The inner message will actually be parsed when it is first accessed. + * + * This is only a hint. Implementations are free to choose whether to use + * eager or lazy parsing regardless of the value of this option. However, + * setting this option true suggests that the protocol author believes that + * using lazy parsing on this field is worth the additional bookkeeping + * overhead typically needed to implement it. + * + * This option does not affect the public interface of any generated code; + * all method signatures remain the same. Furthermore, thread-safety of the + * interface is not affected by this option; const methods remain safe to + * call from multiple threads concurrently, while non-const methods continue + * to require exclusive access. + * + * Note that lazy message fields are still eagerly verified to check + * ill-formed wireformat or missing required fields. Calling IsInitialized() + * on the outer message would fail if the inner message has missing required + * fields. Failed verification would result in parsing failure (except when + * uninitialized messages are acceptable). + * * @generated from field: optional bool lazy = 5 [default = false]; */ lazy?: boolean; /** + * unverified_lazy does no correctness checks on the byte stream. This should + * only be used where lazy with verification is prohibitive for performance + * reasons. + * * @generated from field: optional bool unverified_lazy = 15 [default = false]; */ unverifiedLazy?: boolean; /** + * Is this field deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for accessors, or it will be completely ignored; in the very least, this + * is a formalization for deprecating fields. + * * @generated from field: optional bool deprecated = 3 [default = false]; */ deprecated?: boolean; /** + * For Google-internal migration only. Do not use. + * * @generated from field: optional bool weak = 10 [default = false]; */ weak?: boolean; /** + * Indicate that the field value should not be printed out when using debug + * formats, e.g. when the field contains sensitive credentials. + * * @generated from field: optional bool debug_redact = 16 [default = false]; */ debugRedact?: boolean; @@ -2041,6 +2422,8 @@ export type FieldOptionsJson = { editionDefaults?: FieldOptions_EditionDefaultJson[]; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 21; */ features?: FeatureSetJson; @@ -2051,6 +2434,8 @@ export type FieldOptionsJson = { featureSupport?: FieldOptions_FeatureSupportJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2081,7 +2466,7 @@ export type FieldOptions_EditionDefault = Message<"google.protobuf.FieldOptions. }; /** - * JSON type for the message google.protobuf.FieldOptions.EditionDefault. + * @generated from message google.protobuf.FieldOptions.EditionDefault */ export type FieldOptions_EditionDefaultJson = { /** @@ -2090,6 +2475,8 @@ export type FieldOptions_EditionDefaultJson = { edition?: EditionJson; /** + * Textproto value. + * * @generated from field: optional string value = 2; */ value?: string; @@ -2144,25 +2531,41 @@ export type FieldOptions_FeatureSupport = Message<"google.protobuf.FieldOptions. }; /** - * JSON type for the message google.protobuf.FieldOptions.FeatureSupport. + * Information about the support window of a feature. + * + * @generated from message google.protobuf.FieldOptions.FeatureSupport */ export type FieldOptions_FeatureSupportJson = { /** + * The edition that this feature was first available in. In editions + * earlier than this one, the default assigned to EDITION_LEGACY will be + * used, and proto files will not be able to override it. + * * @generated from field: optional google.protobuf.Edition edition_introduced = 1; */ editionIntroduced?: EditionJson; /** + * The edition this feature becomes deprecated in. Using this after this + * edition may trigger warnings. + * * @generated from field: optional google.protobuf.Edition edition_deprecated = 2; */ editionDeprecated?: EditionJson; /** + * The deprecation warning text if this feature is used after the edition it + * was marked deprecated in. + * * @generated from field: optional string deprecation_warning = 3; */ deprecationWarning?: string; /** + * The edition this feature is no longer available in. In editions after + * this one, the last default assigned will be used, and proto files will + * not be able to override it. + * * @generated from field: optional google.protobuf.Edition edition_removed = 4; */ editionRemoved?: EditionJson; @@ -2205,7 +2608,7 @@ export enum FieldOptions_CType { } /** - * JSON type for the enum google.protobuf.FieldOptions.CType. + * @generated from enum google.protobuf.FieldOptions.CType */ export type FieldOptions_CTypeJson = "STRING" | "CORD" | "STRING_PIECE"; @@ -2242,7 +2645,7 @@ export enum FieldOptions_JSType { } /** - * JSON type for the enum google.protobuf.FieldOptions.JSType. + * @generated from enum google.protobuf.FieldOptions.JSType */ export type FieldOptions_JSTypeJson = "JS_NORMAL" | "JS_STRING" | "JS_NUMBER"; @@ -2277,7 +2680,11 @@ export enum FieldOptions_OptionRetention { } /** - * JSON type for the enum google.protobuf.FieldOptions.OptionRetention. + * If set to RETENTION_SOURCE, the option will be omitted from the binary. + * Note: as of January 2023, support for this is in progress and does not yet + * have an effect (b/264593489). + * + * @generated from enum google.protobuf.FieldOptions.OptionRetention */ export type FieldOptions_OptionRetentionJson = "RETENTION_UNKNOWN" | "RETENTION_RUNTIME" | "RETENTION_SOURCE"; @@ -2348,7 +2755,12 @@ export enum FieldOptions_OptionTargetType { } /** - * JSON type for the enum google.protobuf.FieldOptions.OptionTargetType. + * This indicates the types of entities that the field may apply to when used + * as an option. If it is unset, then the field may be freely used as an + * option on any kind of entity. Note: as of January 2023, support for this is + * in progress and does not yet have an effect (b/264593489). + * + * @generated from enum google.protobuf.FieldOptions.OptionTargetType */ export type FieldOptions_OptionTargetTypeJson = "TARGET_TYPE_UNKNOWN" | "TARGET_TYPE_FILE" | "TARGET_TYPE_EXTENSION_RANGE" | "TARGET_TYPE_MESSAGE" | "TARGET_TYPE_FIELD" | "TARGET_TYPE_ONEOF" | "TARGET_TYPE_ENUM" | "TARGET_TYPE_ENUM_ENTRY" | "TARGET_TYPE_SERVICE" | "TARGET_TYPE_METHOD"; @@ -2378,15 +2790,19 @@ export type OneofOptions = Message<"google.protobuf.OneofOptions"> & { }; /** - * JSON type for the message google.protobuf.OneofOptions. + * @generated from message google.protobuf.OneofOptions */ export type OneofOptionsJson = { /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 1; */ features?: FeatureSetJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2450,30 +2866,50 @@ export type EnumOptions = Message<"google.protobuf.EnumOptions"> & { }; /** - * JSON type for the message google.protobuf.EnumOptions. + * @generated from message google.protobuf.EnumOptions */ export type EnumOptionsJson = { /** + * Set this option to true to allow mapping different tag names to the same + * value. + * * @generated from field: optional bool allow_alias = 2; */ allowAlias?: boolean; /** + * Is this enum deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for the enum, or it will be completely ignored; in the very least, this + * is a formalization for deprecating enums. + * * @generated from field: optional bool deprecated = 3 [default = false]; */ deprecated?: boolean; /** + * Enable the legacy handling of JSON field name conflicts. This lowercases + * and strips underscored from the fields before comparison in proto3 only. + * The new behavior takes `json_name` into account and applies to proto2 as + * well. + * TODO Remove this legacy behavior once downstream teams have + * had time to migrate. + * * @generated from field: optional bool deprecated_legacy_json_field_conflicts = 6 [deprecated = true]; + * @deprecated */ deprecatedLegacyJsonFieldConflicts?: boolean; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 7; */ features?: FeatureSetJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2532,30 +2968,45 @@ export type EnumValueOptions = Message<"google.protobuf.EnumValueOptions"> & { }; /** - * JSON type for the message google.protobuf.EnumValueOptions. + * @generated from message google.protobuf.EnumValueOptions */ export type EnumValueOptionsJson = { /** + * Is this enum value deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for the enum value, or it will be completely ignored; in the very least, + * this is a formalization for deprecating enum values. + * * @generated from field: optional bool deprecated = 1 [default = false]; */ deprecated?: boolean; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 2; */ features?: FeatureSetJson; /** + * Indicate that fields annotated with this enum value should not be printed + * out when using debug formats, e.g. when the field contains sensitive + * credentials. + * * @generated from field: optional bool debug_redact = 3 [default = false]; */ debugRedact?: boolean; /** + * Information about the support window of a feature value. + * * @generated from field: optional google.protobuf.FieldOptions.FeatureSupport feature_support = 4; */ featureSupport?: FieldOptions_FeatureSupportJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2598,20 +3049,29 @@ export type ServiceOptions = Message<"google.protobuf.ServiceOptions"> & { }; /** - * JSON type for the message google.protobuf.ServiceOptions. + * @generated from message google.protobuf.ServiceOptions */ export type ServiceOptionsJson = { /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 34; */ features?: FeatureSetJson; /** + * Is this service deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for the service, or it will be completely ignored; in the very least, + * this is a formalization for deprecating services. + * * @generated from field: optional bool deprecated = 33 [default = false]; */ deprecated?: boolean; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2659,10 +3119,15 @@ export type MethodOptions = Message<"google.protobuf.MethodOptions"> & { }; /** - * JSON type for the message google.protobuf.MethodOptions. + * @generated from message google.protobuf.MethodOptions */ export type MethodOptionsJson = { /** + * Is this method deprecated? + * Depending on the target platform, this can emit Deprecated annotations + * for the method, or it will be completely ignored; in the very least, + * this is a formalization for deprecating methods. + * * @generated from field: optional bool deprecated = 33 [default = false]; */ deprecated?: boolean; @@ -2673,11 +3138,15 @@ export type MethodOptionsJson = { idempotencyLevel?: MethodOptions_IdempotencyLevelJson; /** + * Any features defined in the specific edition. + * * @generated from field: optional google.protobuf.FeatureSet features = 35; */ features?: FeatureSetJson; /** + * The parser stores options it doesn't recognize here. See above. + * * @generated from field: repeated google.protobuf.UninterpretedOption uninterpreted_option = 999; */ uninterpretedOption?: UninterpretedOptionJson[]; @@ -2719,7 +3188,11 @@ export enum MethodOptions_IdempotencyLevel { } /** - * JSON type for the enum google.protobuf.MethodOptions.IdempotencyLevel. + * Is this method side-effect-free (or safe in HTTP parlance), or idempotent, + * or neither? HTTP based RPC implementation may choose GET verb for safe + * methods, and PUT verb for idempotent methods instead of the default POST. + * + * @generated from enum google.protobuf.MethodOptions.IdempotencyLevel */ export type MethodOptions_IdempotencyLevelJson = "IDEMPOTENCY_UNKNOWN" | "NO_SIDE_EFFECTS" | "IDEMPOTENT"; @@ -2780,7 +3253,14 @@ export type UninterpretedOption = Message<"google.protobuf.UninterpretedOption"> }; /** - * JSON type for the message google.protobuf.UninterpretedOption. + * A message representing a option the parser does not recognize. This only + * appears in options protos created by the compiler::Parser class. + * DescriptorPool resolves these when building Descriptor objects. Therefore, + * options protos in descriptor objects (e.g. returned by Descriptor::options(), + * or produced by Descriptor::CopyTo()) will never have UninterpretedOptions + * in them. + * + * @generated from message google.protobuf.UninterpretedOption */ export type UninterpretedOptionJson = { /** @@ -2789,6 +3269,9 @@ export type UninterpretedOptionJson = { name?: UninterpretedOption_NamePartJson[]; /** + * The value of the uninterpreted option, in whatever type the tokenizer + * identified it as during parsing. Exactly one of these should be set. + * * @generated from field: optional string identifier_value = 3; */ identifierValue?: string; @@ -2848,7 +3331,13 @@ export type UninterpretedOption_NamePart = Message<"google.protobuf.Uninterprete }; /** - * JSON type for the message google.protobuf.UninterpretedOption.NamePart. + * The name of the uninterpreted option. Each string represents a segment in + * a dot-separated name. is_extension is true iff a segment represents an + * extension (denoted with parentheses in options specs in .proto files). + * E.g.,{ ["foo", false], ["bar.baz", true], ["moo", false] } represents + * "foo.(bar.baz).moo". + * + * @generated from message google.protobuf.UninterpretedOption.NamePart */ export type UninterpretedOption_NamePartJson = { /** @@ -2912,7 +3401,14 @@ export type FeatureSet = Message<"google.protobuf.FeatureSet"> & { }; /** - * JSON type for the message google.protobuf.FeatureSet. + * TODO Enums in C++ gencode (and potentially other languages) are + * not well scoped. This means that each of the feature enums below can clash + * with each other. The short names we've chosen maximize call-site + * readability, but leave us very open to this scenario. A future feature will + * be designed and implemented to handle this, hopefully before we ever hit a + * conflict here. + * + * @generated from message google.protobuf.FeatureSet */ export type FeatureSetJson = { /** @@ -2979,7 +3475,7 @@ export enum FeatureSet_FieldPresence { } /** - * JSON type for the enum google.protobuf.FeatureSet.FieldPresence. + * @generated from enum google.protobuf.FeatureSet.FieldPresence */ export type FeatureSet_FieldPresenceJson = "FIELD_PRESENCE_UNKNOWN" | "EXPLICIT" | "IMPLICIT" | "LEGACY_REQUIRED"; @@ -3010,7 +3506,7 @@ export enum FeatureSet_EnumType { } /** - * JSON type for the enum google.protobuf.FeatureSet.EnumType. + * @generated from enum google.protobuf.FeatureSet.EnumType */ export type FeatureSet_EnumTypeJson = "ENUM_TYPE_UNKNOWN" | "OPEN" | "CLOSED"; @@ -3041,7 +3537,7 @@ export enum FeatureSet_RepeatedFieldEncoding { } /** - * JSON type for the enum google.protobuf.FeatureSet.RepeatedFieldEncoding. + * @generated from enum google.protobuf.FeatureSet.RepeatedFieldEncoding */ export type FeatureSet_RepeatedFieldEncodingJson = "REPEATED_FIELD_ENCODING_UNKNOWN" | "PACKED" | "EXPANDED"; @@ -3072,7 +3568,7 @@ export enum FeatureSet_Utf8Validation { } /** - * JSON type for the enum google.protobuf.FeatureSet.Utf8Validation. + * @generated from enum google.protobuf.FeatureSet.Utf8Validation */ export type FeatureSet_Utf8ValidationJson = "UTF8_VALIDATION_UNKNOWN" | "VERIFY" | "NONE"; @@ -3103,7 +3599,7 @@ export enum FeatureSet_MessageEncoding { } /** - * JSON type for the enum google.protobuf.FeatureSet.MessageEncoding. + * @generated from enum google.protobuf.FeatureSet.MessageEncoding */ export type FeatureSet_MessageEncodingJson = "MESSAGE_ENCODING_UNKNOWN" | "LENGTH_PREFIXED" | "DELIMITED"; @@ -3134,7 +3630,7 @@ export enum FeatureSet_JsonFormat { } /** - * JSON type for the enum google.protobuf.FeatureSet.JsonFormat. + * @generated from enum google.protobuf.FeatureSet.JsonFormat */ export type FeatureSet_JsonFormatJson = "JSON_FORMAT_UNKNOWN" | "ALLOW" | "LEGACY_BEST_EFFORT"; @@ -3176,7 +3672,12 @@ export type FeatureSetDefaults = Message<"google.protobuf.FeatureSetDefaults"> & }; /** - * JSON type for the message google.protobuf.FeatureSetDefaults. + * A compiled specification for the defaults of a set of features. These + * messages are generated from FeatureSet extensions and can be used to seed + * feature resolution. The resolution with this object becomes a simple search + * for the closest matching edition, followed by proto merges. + * + * @generated from message google.protobuf.FeatureSetDefaults */ export type FeatureSetDefaultsJson = { /** @@ -3185,11 +3686,17 @@ export type FeatureSetDefaultsJson = { defaults?: FeatureSetDefaults_FeatureSetEditionDefaultJson[]; /** + * The minimum supported edition (inclusive) when this was constructed. + * Editions before this will not have defaults. + * * @generated from field: optional google.protobuf.Edition minimum_edition = 4; */ minimumEdition?: EditionJson; /** + * The maximum known edition (inclusive) when this was constructed. Editions + * after this will not have reliable defaults. + * * @generated from field: optional google.protobuf.Edition maximum_edition = 5; */ maximumEdition?: EditionJson; @@ -3232,7 +3739,12 @@ export type FeatureSetDefaults_FeatureSetEditionDefault = Message<"google.protob }; /** - * JSON type for the message google.protobuf.FeatureSetDefaults.FeatureSetEditionDefault. + * A map from every known edition with a unique set of defaults to its + * defaults. Not all editions may be contained here. For a given edition, + * the defaults at the closest matching edition ordered at or before it should + * be used. This field must be in strict ascending order by edition. + * + * @generated from message google.protobuf.FeatureSetDefaults.FeatureSetEditionDefault */ export type FeatureSetDefaults_FeatureSetEditionDefaultJson = { /** @@ -3241,11 +3753,15 @@ export type FeatureSetDefaults_FeatureSetEditionDefaultJson = { edition?: EditionJson; /** + * Defaults of features that can be overridden in this edition. + * * @generated from field: optional google.protobuf.FeatureSet overridable_features = 4; */ overridableFeatures?: FeatureSetJson; /** + * Defaults of features that can't be overridden in this edition. + * * @generated from field: optional google.protobuf.FeatureSet fixed_features = 5; */ fixedFeatures?: FeatureSetJson; @@ -3316,10 +3832,57 @@ export type SourceCodeInfo = Message<"google.protobuf.SourceCodeInfo"> & { }; /** - * JSON type for the message google.protobuf.SourceCodeInfo. + * Encapsulates information about the original source file from which a + * FileDescriptorProto was generated. + * + * @generated from message google.protobuf.SourceCodeInfo */ export type SourceCodeInfoJson = { /** + * A Location identifies a piece of source code in a .proto file which + * corresponds to a particular definition. This information is intended + * to be useful to IDEs, code indexers, documentation generators, and similar + * tools. + * + * For example, say we have a file like: + * message Foo { + * optional string foo = 1; + * } + * Let's look at just the field definition: + * optional string foo = 1; + * ^ ^^ ^^ ^ ^^^ + * a bc de f ghi + * We have the following locations: + * span path represents + * [a,i) [ 4, 0, 2, 0 ] The whole field definition. + * [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). + * [c,d) [ 4, 0, 2, 0, 5 ] The type (string). + * [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). + * [g,h) [ 4, 0, 2, 0, 3 ] The number (1). + * + * Notes: + * - A location may refer to a repeated field itself (i.e. not to any + * particular index within it). This is used whenever a set of elements are + * logically enclosed in a single code segment. For example, an entire + * extend block (possibly containing multiple extension definitions) will + * have an outer location whose path refers to the "extensions" repeated + * field without an index. + * - Multiple locations may have the same path. This happens when a single + * logical declaration is spread out across multiple places. The most + * obvious example is the "extend" block again -- there may be multiple + * extend blocks in the same scope, each of which will have the same path. + * - A location's span is not always a subset of its parent's span. For + * example, the "extendee" of an extension declaration appears at the + * beginning of the "extend" block and is shared by all extensions within + * the block. + * - Just because a location's span is a subset of some other location's span + * does not mean that it is a descendant. For example, a "group" defines + * both a type and a field in a single declaration. Thus, the locations + * corresponding to the type and field and their components will overlap. + * - Code which tries to interpret locations should probably be designed to + * ignore those that it doesn't understand, as more types of locations could + * be recorded in the future. + * * @generated from field: repeated google.protobuf.SourceCodeInfo.Location location = 1; */ location?: SourceCodeInfo_LocationJson[]; @@ -3441,20 +4004,98 @@ export type SourceCodeInfo_Location = Message<"google.protobuf.SourceCodeInfo.Lo }; /** - * JSON type for the message google.protobuf.SourceCodeInfo.Location. + * @generated from message google.protobuf.SourceCodeInfo.Location */ export type SourceCodeInfo_LocationJson = { /** + * Identifies which part of the FileDescriptorProto was defined at this + * location. + * + * Each element is a field number or an index. They form a path from + * the root FileDescriptorProto to the place where the definition appears. + * For example, this path: + * [ 4, 3, 2, 7, 1 ] + * refers to: + * file.message_type(3) // 4, 3 + * .field(7) // 2, 7 + * .name() // 1 + * This is because FileDescriptorProto.message_type has field number 4: + * repeated DescriptorProto message_type = 4; + * and DescriptorProto.field has field number 2: + * repeated FieldDescriptorProto field = 2; + * and FieldDescriptorProto.name has field number 1: + * optional string name = 1; + * + * Thus, the above path gives the location of a field name. If we removed + * the last element: + * [ 4, 3, 2, 7 ] + * this path refers to the whole field declaration (from the beginning + * of the label to the terminating semicolon). + * * @generated from field: repeated int32 path = 1 [packed = true]; */ path?: number[]; /** + * Always has exactly three or four elements: start line, start column, + * end line (optional, otherwise assumed same as start line), end column. + * These are packed into a single field for efficiency. Note that line + * and column numbers are zero-based -- typically you will want to add + * 1 to each before displaying to a user. + * * @generated from field: repeated int32 span = 2 [packed = true]; */ span?: number[]; /** + * If this SourceCodeInfo represents a complete declaration, these are any + * comments appearing before and after the declaration which appear to be + * attached to the declaration. + * + * A series of line comments appearing on consecutive lines, with no other + * tokens appearing on those lines, will be treated as a single comment. + * + * leading_detached_comments will keep paragraphs of comments that appear + * before (but not connected to) the current element. Each paragraph, + * separated by empty lines, will be one comment element in the repeated + * field. + * + * Only the comment content is provided; comment markers (e.g. //) are + * stripped out. For block comments, leading whitespace and an asterisk + * will be stripped from the beginning of each line other than the first. + * Newlines are included in the output. + * + * Examples: + * + * optional int32 foo = 1; // Comment attached to foo. + * // Comment attached to bar. + * optional int32 bar = 2; + * + * optional string baz = 3; + * // Comment attached to baz. + * // Another line attached to baz. + * + * // Comment attached to moo. + * // + * // Another line attached to moo. + * optional double moo = 4; + * + * // Detached comment for corge. This is not leading or trailing comments + * // to moo or corge because there are blank lines separating it from + * // both. + * + * // Detached comment for corge paragraph 2. + * + * optional string corge = 5; + * /* Block comment attached + * * to corge. Leading asterisks + * * will be removed. *\/ + * /* Block comment attached to + * * grault. *\/ + * optional int32 grault = 6; + * + * // ignored detached comments. + * * @generated from field: optional string leading_comments = 3; */ leadingComments?: string; @@ -3495,10 +4136,17 @@ export type GeneratedCodeInfo = Message<"google.protobuf.GeneratedCodeInfo"> & { }; /** - * JSON type for the message google.protobuf.GeneratedCodeInfo. + * Describes the relationship between generated code and its original source + * file. A GeneratedCodeInfo message is associated with only one generated + * source file, but may contain references to different source .proto files. + * + * @generated from message google.protobuf.GeneratedCodeInfo */ export type GeneratedCodeInfoJson = { /** + * An Annotation connects some span of text in generated code to an element + * of its generating .proto file. + * * @generated from field: repeated google.protobuf.GeneratedCodeInfo.Annotation annotation = 1; */ annotation?: GeneratedCodeInfo_AnnotationJson[]; @@ -3554,25 +4202,37 @@ export type GeneratedCodeInfo_Annotation = Message<"google.protobuf.GeneratedCod }; /** - * JSON type for the message google.protobuf.GeneratedCodeInfo.Annotation. + * @generated from message google.protobuf.GeneratedCodeInfo.Annotation */ export type GeneratedCodeInfo_AnnotationJson = { /** + * Identifies the element in the original source .proto file. This field + * is formatted the same as SourceCodeInfo.Location.path. + * * @generated from field: repeated int32 path = 1 [packed = true]; */ path?: number[]; /** + * Identifies the filesystem path to the original source .proto. + * * @generated from field: optional string source_file = 2; */ sourceFile?: string; /** + * Identifies the starting offset in bytes in the generated code + * that relates to the identified object. + * * @generated from field: optional int32 begin = 3; */ begin?: number; /** + * Identifies the ending offset in bytes in the generated code that + * relates to the identified object. The end offset should be one past + * the last relevant byte (so the length of the text = end - begin). + * * @generated from field: optional int32 end = 4; */ end?: number; @@ -3620,7 +4280,10 @@ export enum GeneratedCodeInfo_Annotation_Semantic { } /** - * JSON type for the enum google.protobuf.GeneratedCodeInfo.Annotation.Semantic. + * Represents the identified object's effect on the element in the original + * .proto file. + * + * @generated from enum google.protobuf.GeneratedCodeInfo.Annotation.Semantic */ export type GeneratedCodeInfo_Annotation_SemanticJson = "NONE" | "SET" | "ALIAS"; @@ -3719,7 +4382,9 @@ export enum Edition { } /** - * JSON type for the enum google.protobuf.Edition. + * The full set of known editions. + * + * @generated from enum google.protobuf.Edition */ export type EditionJson = "EDITION_UNKNOWN" | "EDITION_LEGACY" | "EDITION_PROTO2" | "EDITION_PROTO3" | "EDITION_2023" | "EDITION_2024" | "EDITION_1_TEST_ONLY" | "EDITION_2_TEST_ONLY" | "EDITION_99997_TEST_ONLY" | "EDITION_99998_TEST_ONLY" | "EDITION_99999_TEST_ONLY" | "EDITION_MAX"; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/duration_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/duration_pb.ts index 82575611f..370ba516d 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/duration_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/duration_pb.ts @@ -114,7 +114,67 @@ export type Duration = Message<"google.protobuf.Duration"> & { }; /** - * JSON type for the message google.protobuf.Duration. + * A Duration represents a signed, fixed-length span of time represented + * as a count of seconds and fractions of seconds at nanosecond + * resolution. It is independent of any calendar and concepts like "day" + * or "month". It is related to Timestamp in that the difference between + * two Timestamp values is a Duration and it can be added or subtracted + * from a Timestamp. Range is approximately +-10,000 years. + * + * # Examples + * + * Example 1: Compute Duration from two Timestamps in pseudo code. + * + * Timestamp start = ...; + * Timestamp end = ...; + * Duration duration = ...; + * + * duration.seconds = end.seconds - start.seconds; + * duration.nanos = end.nanos - start.nanos; + * + * if (duration.seconds < 0 && duration.nanos > 0) { + * duration.seconds += 1; + * duration.nanos -= 1000000000; + * } else if (duration.seconds > 0 && duration.nanos < 0) { + * duration.seconds -= 1; + * duration.nanos += 1000000000; + * } + * + * Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + * + * Timestamp start = ...; + * Duration duration = ...; + * Timestamp end = ...; + * + * end.seconds = start.seconds + duration.seconds; + * end.nanos = start.nanos + duration.nanos; + * + * if (end.nanos < 0) { + * end.seconds -= 1; + * end.nanos += 1000000000; + * } else if (end.nanos >= 1000000000) { + * end.seconds += 1; + * end.nanos -= 1000000000; + * } + * + * Example 3: Compute Duration from datetime.timedelta in Python. + * + * td = datetime.timedelta(days=3, minutes=10) + * duration = Duration() + * duration.FromTimedelta(td) + * + * # JSON Mapping + * + * In JSON format, the Duration type is encoded as a string rather than an + * object, where the string ends in the suffix "s" (indicating seconds) and + * is preceded by the number of seconds, with nanoseconds expressed as + * fractional seconds. For example, 3 seconds with 0 nanoseconds should be + * encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should + * be expressed in JSON format as "3.000000001s", and 3 seconds and 1 + * microsecond should be expressed in JSON format as "3.000001s". + * + * + * @generated from message google.protobuf.Duration */ export type DurationJson = string; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/empty_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/empty_pb.ts index 433521312..a57b56f2c 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/empty_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/empty_pb.ts @@ -43,7 +43,16 @@ export type Empty = Message<"google.protobuf.Empty"> & { }; /** - * JSON type for the message google.protobuf.Empty. + * A generic empty message that you can re-use to avoid defining duplicated + * empty messages in your APIs. A typical example is to use it as the request + * or the response type of an API method. For instance: + * + * service Foo { + * rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); + * } + * + * + * @generated from message google.protobuf.Empty */ export type EmptyJson = Record; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/field_mask_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/field_mask_pb.ts index c97e3aa3e..748bceae7 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/field_mask_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/field_mask_pb.ts @@ -240,7 +240,207 @@ export type FieldMask = Message<"google.protobuf.FieldMask"> & { }; /** - * JSON type for the message google.protobuf.FieldMask. + * `FieldMask` represents a set of symbolic field paths, for example: + * + * paths: "f.a" + * paths: "f.b.d" + * + * Here `f` represents a field in some root message, `a` and `b` + * fields in the message found in `f`, and `d` a field found in the + * message in `f.b`. + * + * Field masks are used to specify a subset of fields that should be + * returned by a get operation or modified by an update operation. + * Field masks also have a custom JSON encoding (see below). + * + * # Field Masks in Projections + * + * When used in the context of a projection, a response message or + * sub-message is filtered by the API to only contain those fields as + * specified in the mask. For example, if the mask in the previous + * example is applied to a response message as follows: + * + * f { + * a : 22 + * b { + * d : 1 + * x : 2 + * } + * y : 13 + * } + * z: 8 + * + * The result will not contain specific values for fields x,y and z + * (their value will be set to the default, and omitted in proto text + * output): + * + * + * f { + * a : 22 + * b { + * d : 1 + * } + * } + * + * A repeated field is not allowed except at the last position of a + * paths string. + * + * If a FieldMask object is not present in a get operation, the + * operation applies to all fields (as if a FieldMask of all fields + * had been specified). + * + * Note that a field mask does not necessarily apply to the + * top-level response message. In case of a REST get operation, the + * field mask applies directly to the response, but in case of a REST + * list operation, the mask instead applies to each individual message + * in the returned resource list. In case of a REST custom method, + * other definitions may be used. Where the mask applies will be + * clearly documented together with its declaration in the API. In + * any case, the effect on the returned resource/resources is required + * behavior for APIs. + * + * # Field Masks in Update Operations + * + * A field mask in update operations specifies which fields of the + * targeted resource are going to be updated. The API is required + * to only change the values of the fields as specified in the mask + * and leave the others untouched. If a resource is passed in to + * describe the updated values, the API ignores the values of all + * fields not covered by the mask. + * + * If a repeated field is specified for an update operation, new values will + * be appended to the existing repeated field in the target resource. Note that + * a repeated field is only allowed in the last position of a `paths` string. + * + * If a sub-message is specified in the last position of the field mask for an + * update operation, then new value will be merged into the existing sub-message + * in the target resource. + * + * For example, given the target message: + * + * f { + * b { + * d: 1 + * x: 2 + * } + * c: [1] + * } + * + * And an update message: + * + * f { + * b { + * d: 10 + * } + * c: [2] + * } + * + * then if the field mask is: + * + * paths: ["f.b", "f.c"] + * + * then the result will be: + * + * f { + * b { + * d: 10 + * x: 2 + * } + * c: [1, 2] + * } + * + * An implementation may provide options to override this default behavior for + * repeated and message fields. + * + * In order to reset a field's value to the default, the field must + * be in the mask and set to the default value in the provided resource. + * Hence, in order to reset all fields of a resource, provide a default + * instance of the resource and set all fields in the mask, or do + * not provide a mask as described below. + * + * If a field mask is not present on update, the operation applies to + * all fields (as if a field mask of all fields has been specified). + * Note that in the presence of schema evolution, this may mean that + * fields the client does not know and has therefore not filled into + * the request will be reset to their default. If this is unwanted + * behavior, a specific service may require a client to always specify + * a field mask, producing an error if not. + * + * As with get operations, the location of the resource which + * describes the updated values in the request message depends on the + * operation kind. In any case, the effect of the field mask is + * required to be honored by the API. + * + * ## Considerations for HTTP REST + * + * The HTTP kind of an update operation which uses a field mask must + * be set to PATCH instead of PUT in order to satisfy HTTP semantics + * (PUT must only be used for full updates). + * + * # JSON Encoding of Field Masks + * + * In JSON, a field mask is encoded as a single string where paths are + * separated by a comma. Fields name in each path are converted + * to/from lower-camel naming conventions. + * + * As an example, consider the following message declarations: + * + * message Profile { + * User user = 1; + * Photo photo = 2; + * } + * message User { + * string display_name = 1; + * string address = 2; + * } + * + * In proto a field mask for `Profile` may look as such: + * + * mask { + * paths: "user.display_name" + * paths: "photo" + * } + * + * In JSON, the same mask is represented as below: + * + * { + * mask: "user.displayName,photo" + * } + * + * # Field Masks and Oneof Fields + * + * Field masks treat fields in oneofs just as regular fields. Consider the + * following message: + * + * message SampleMessage { + * oneof test_oneof { + * string name = 4; + * SubMessage sub_message = 9; + * } + * } + * + * The field mask can be: + * + * mask { + * paths: "name" + * } + * + * Or: + * + * mask { + * paths: "sub_message" + * } + * + * Note that oneof type names ("test_oneof" in this case) cannot be used in + * paths. + * + * ## Field Mask Verification + * + * The implementation of any API method which has a FieldMask type field in the + * request should verify the included field paths, and return an + * `INVALID_ARGUMENT` error if any path is unmappable. + * + * @generated from message google.protobuf.FieldMask */ export type FieldMaskJson = string; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/source_context_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/source_context_pb.ts index 34901d45d..a0b72288e 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/source_context_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/source_context_pb.ts @@ -44,10 +44,16 @@ export type SourceContext = Message<"google.protobuf.SourceContext"> & { }; /** - * JSON type for the message google.protobuf.SourceContext. + * `SourceContext` represents information about the source of a + * protobuf element, like the file in which it is defined. + * + * @generated from message google.protobuf.SourceContext */ export type SourceContextJson = { /** + * The path-qualified name of the .proto file that contained the associated + * protobuf element. For example: `"google/protobuf/source_context.proto"`. + * * @generated from field: string file_name = 1; */ fileName?: string; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/struct_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/struct_pb.ts index 5a9077381..e98906539 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/struct_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/struct_pb.ts @@ -51,7 +51,16 @@ export type Struct = Message<"google.protobuf.Struct"> & { }; /** - * JSON type for the message google.protobuf.Struct. + * `Struct` represents a structured data value, consisting of fields + * which map to dynamically typed values. In some languages, `Struct` + * might be supported by a native representation. For example, in + * scripting languages like JS a struct is represented as an + * object. The details of that representation are described together + * with the proto support for the language. + * + * The JSON representation for `Struct` is JSON object. + * + * @generated from message google.protobuf.Struct */ export type StructJson = JsonObject; @@ -130,7 +139,14 @@ export type Value = Message<"google.protobuf.Value"> & { }; /** - * JSON type for the message google.protobuf.Value. + * `Value` represents a dynamically typed value which can be either + * null, a number, a string, a boolean, a recursive struct value, or a + * list of values. A producer of value is expected to set one of these + * variants. Absence of any variant indicates an error. + * + * The JSON representation for `Value` is JSON value. + * + * @generated from message google.protobuf.Value */ export type ValueJson = JsonValue; @@ -158,7 +174,11 @@ export type ListValue = Message<"google.protobuf.ListValue"> & { }; /** - * JSON type for the message google.protobuf.ListValue. + * `ListValue` is a wrapper around a repeated field of values. + * + * The JSON representation for `ListValue` is JSON array. + * + * @generated from message google.protobuf.ListValue */ export type ListValueJson = JsonValue[]; @@ -187,7 +207,12 @@ export enum NullValue { } /** - * JSON type for the enum google.protobuf.NullValue. + * `NullValue` is a singleton enumeration to represent the null value for the + * `Value` type union. + * + * The JSON representation for `NullValue` is JSON `null`. + * + * @generated from enum google.protobuf.NullValue */ export type NullValueJson = null; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/timestamp_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/timestamp_pb.ts index c11741032..0ba38dd30 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/timestamp_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/timestamp_pb.ts @@ -143,7 +143,98 @@ export type Timestamp = Message<"google.protobuf.Timestamp"> & { }; /** - * JSON type for the message google.protobuf.Timestamp. + * A Timestamp represents a point in time independent of any time zone or local + * calendar, encoded as a count of seconds and fractions of seconds at + * nanosecond resolution. The count is relative to an epoch at UTC midnight on + * January 1, 1970, in the proleptic Gregorian calendar which extends the + * Gregorian calendar backwards to year one. + * + * All minutes are 60 seconds long. Leap seconds are "smeared" so that no leap + * second table is needed for interpretation, using a [24-hour linear + * smear](https://developers.google.com/time/smear). + * + * The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By + * restricting to that range, we ensure that we can convert to and from [RFC + * 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings. + * + * # Examples + * + * Example 1: Compute Timestamp from POSIX `time()`. + * + * Timestamp timestamp; + * timestamp.set_seconds(time(NULL)); + * timestamp.set_nanos(0); + * + * Example 2: Compute Timestamp from POSIX `gettimeofday()`. + * + * struct timeval tv; + * gettimeofday(&tv, NULL); + * + * Timestamp timestamp; + * timestamp.set_seconds(tv.tv_sec); + * timestamp.set_nanos(tv.tv_usec * 1000); + * + * Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + * + * FILETIME ft; + * GetSystemTimeAsFileTime(&ft); + * UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + * + * // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + * // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + * Timestamp timestamp; + * timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + * timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + * + * Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + * + * long millis = System.currentTimeMillis(); + * + * Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + * .setNanos((int) ((millis % 1000) * 1000000)).build(); + * + * Example 5: Compute Timestamp from Java `Instant.now()`. + * + * Instant now = Instant.now(); + * + * Timestamp timestamp = + * Timestamp.newBuilder().setSeconds(now.getEpochSecond()) + * .setNanos(now.getNano()).build(); + * + * Example 6: Compute Timestamp from current time in Python. + * + * timestamp = Timestamp() + * timestamp.GetCurrentTime() + * + * # JSON Mapping + * + * In JSON format, the Timestamp type is encoded as a string in the + * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the + * format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" + * where {year} is always expressed using four digits while {month}, {day}, + * {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional + * seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), + * are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone + * is required. A proto3 JSON serializer should always use UTC (as indicated by + * "Z") when printing the Timestamp type and a proto3 JSON parser should be + * able to accept both UTC and other timezones (as indicated by an offset). + * + * For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past + * 01:30 UTC on January 15, 2017. + * + * In JavaScript, one can convert a Date object to this format using the + * standard + * [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) + * method. In Python, a standard `datetime.datetime` object can be converted + * to this format using + * [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with + * the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use + * the Joda Time's [`ISODateTimeFormat.dateTime()`]( + * http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime() + * ) to obtain a formatter capable of generating timestamps in this format. + * + * + * @generated from message google.protobuf.Timestamp */ export type TimestampJson = string; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/type_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/type_pb.ts index c7fa460e9..e41f5abdc 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/type_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/type_pb.ts @@ -89,40 +89,56 @@ export type Type = Message<"google.protobuf.Type"> & { }; /** - * JSON type for the message google.protobuf.Type. + * A protocol buffer message type. + * + * @generated from message google.protobuf.Type */ export type TypeJson = { /** + * The fully qualified message name. + * * @generated from field: string name = 1; */ name?: string; /** + * The list of fields. + * * @generated from field: repeated google.protobuf.Field fields = 2; */ fields?: FieldJson[]; /** + * The list of types appearing in `oneof` definitions in this type. + * * @generated from field: repeated string oneofs = 3; */ oneofs?: string[]; /** + * The protocol buffer options. + * * @generated from field: repeated google.protobuf.Option options = 4; */ options?: OptionJson[]; /** + * The source context. + * * @generated from field: google.protobuf.SourceContext source_context = 5; */ sourceContext?: SourceContextJson; /** + * The source syntax. + * * @generated from field: google.protobuf.Syntax syntax = 6; */ syntax?: SyntaxJson; /** + * The source edition string, only valid when syntax is SYNTAX_EDITIONS. + * * @generated from field: string edition = 7; */ edition?: string; @@ -215,55 +231,79 @@ export type Field = Message<"google.protobuf.Field"> & { }; /** - * JSON type for the message google.protobuf.Field. + * A single field of a message type. + * + * @generated from message google.protobuf.Field */ export type FieldJson = { /** + * The field type. + * * @generated from field: google.protobuf.Field.Kind kind = 1; */ kind?: Field_KindJson; /** + * The field cardinality. + * * @generated from field: google.protobuf.Field.Cardinality cardinality = 2; */ cardinality?: Field_CardinalityJson; /** + * The field number. + * * @generated from field: int32 number = 3; */ number?: number; /** + * The field name. + * * @generated from field: string name = 4; */ name?: string; /** + * The field type URL, without the scheme, for message or enumeration + * types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. + * * @generated from field: string type_url = 6; */ typeUrl?: string; /** + * The index of the field type in `Type.oneofs`, for message or enumeration + * types. The first type has index 1; zero means the type is not in the list. + * * @generated from field: int32 oneof_index = 7; */ oneofIndex?: number; /** + * Whether to use alternative packed wire representation. + * * @generated from field: bool packed = 8; */ packed?: boolean; /** + * The protocol buffer options. + * * @generated from field: repeated google.protobuf.Option options = 9; */ options?: OptionJson[]; /** + * The field JSON name. + * * @generated from field: string json_name = 10; */ jsonName?: string; /** + * The string value of the default value of this field. Proto2 syntax only. + * * @generated from field: string default_value = 11; */ defaultValue?: string; @@ -417,7 +457,9 @@ export enum Field_Kind { } /** - * JSON type for the enum google.protobuf.Field.Kind. + * Basic field types. + * + * @generated from enum google.protobuf.Field.Kind */ export type Field_KindJson = "TYPE_UNKNOWN" | "TYPE_DOUBLE" | "TYPE_FLOAT" | "TYPE_INT64" | "TYPE_UINT64" | "TYPE_INT32" | "TYPE_FIXED64" | "TYPE_FIXED32" | "TYPE_BOOL" | "TYPE_STRING" | "TYPE_GROUP" | "TYPE_MESSAGE" | "TYPE_BYTES" | "TYPE_UINT32" | "TYPE_ENUM" | "TYPE_SFIXED32" | "TYPE_SFIXED64" | "TYPE_SINT32" | "TYPE_SINT64"; @@ -463,7 +505,9 @@ export enum Field_Cardinality { } /** - * JSON type for the enum google.protobuf.Field.Cardinality. + * Whether a field is optional, required, or repeated. + * + * @generated from enum google.protobuf.Field.Cardinality */ export type Field_CardinalityJson = "CARDINALITY_UNKNOWN" | "CARDINALITY_OPTIONAL" | "CARDINALITY_REQUIRED" | "CARDINALITY_REPEATED"; @@ -523,35 +567,49 @@ export type Enum = Message<"google.protobuf.Enum"> & { }; /** - * JSON type for the message google.protobuf.Enum. + * Enum type definition. + * + * @generated from message google.protobuf.Enum */ export type EnumJson = { /** + * Enum type name. + * * @generated from field: string name = 1; */ name?: string; /** + * Enum value definitions. + * * @generated from field: repeated google.protobuf.EnumValue enumvalue = 2; */ enumvalue?: EnumValueJson[]; /** + * Protocol buffer options. + * * @generated from field: repeated google.protobuf.Option options = 3; */ options?: OptionJson[]; /** + * The source context. + * * @generated from field: google.protobuf.SourceContext source_context = 4; */ sourceContext?: SourceContextJson; /** + * The source syntax. + * * @generated from field: google.protobuf.Syntax syntax = 5; */ syntax?: SyntaxJson; /** + * The source edition string, only valid when syntax is SYNTAX_EDITIONS. + * * @generated from field: string edition = 6; */ edition?: string; @@ -593,20 +651,28 @@ export type EnumValue = Message<"google.protobuf.EnumValue"> & { }; /** - * JSON type for the message google.protobuf.EnumValue. + * Enum value definition. + * + * @generated from message google.protobuf.EnumValue */ export type EnumValueJson = { /** + * Enum value name. + * * @generated from field: string name = 1; */ name?: string; /** + * Enum value number. + * * @generated from field: int32 number = 2; */ number?: number; /** + * Protocol buffer options. + * * @generated from field: repeated google.protobuf.Option options = 3; */ options?: OptionJson[]; @@ -648,15 +714,28 @@ export type Option = Message<"google.protobuf.Option"> & { }; /** - * JSON type for the message google.protobuf.Option. + * A protocol buffer option, which can be attached to a message, field, + * enumeration, etc. + * + * @generated from message google.protobuf.Option */ export type OptionJson = { /** + * The option's name. For protobuf built-in options (options defined in + * descriptor.proto), this is the short name. For example, `"map_entry"`. + * For custom options, it should be the fully-qualified name. For example, + * `"google.api.http"`. + * * @generated from field: string name = 1; */ name?: string; /** + * The option's value packed in an Any message. If the value is a primitive, + * the corresponding wrapper type defined in google/protobuf/wrappers.proto + * should be used. If the value is an enum, it should be stored as an int32 + * value using the google.protobuf.Int32Value type. + * * @generated from field: google.protobuf.Any value = 2; */ value?: AnyJson; @@ -698,7 +777,9 @@ export enum Syntax { } /** - * JSON type for the enum google.protobuf.Syntax. + * The syntax in which a protocol buffer element is defined. + * + * @generated from enum google.protobuf.Syntax */ export type SyntaxJson = "SYNTAX_PROTO2" | "SYNTAX_PROTO3" | "SYNTAX_EDITIONS"; diff --git a/packages/protobuf/src/wkt/gen/google/protobuf/wrappers_pb.ts b/packages/protobuf/src/wkt/gen/google/protobuf/wrappers_pb.ts index 739264b8c..84b883ad8 100644 --- a/packages/protobuf/src/wkt/gen/google/protobuf/wrappers_pb.ts +++ b/packages/protobuf/src/wkt/gen/google/protobuf/wrappers_pb.ts @@ -44,7 +44,11 @@ export type DoubleValue = Message<"google.protobuf.DoubleValue"> & { }; /** - * JSON type for the message google.protobuf.DoubleValue. + * Wrapper message for `double`. + * + * The JSON representation for `DoubleValue` is JSON number. + * + * @generated from message google.protobuf.DoubleValue */ export type DoubleValueJson = number | "NaN" | "Infinity" | "-Infinity"; @@ -72,7 +76,11 @@ export type FloatValue = Message<"google.protobuf.FloatValue"> & { }; /** - * JSON type for the message google.protobuf.FloatValue. + * Wrapper message for `float`. + * + * The JSON representation for `FloatValue` is JSON number. + * + * @generated from message google.protobuf.FloatValue */ export type FloatValueJson = number | "NaN" | "Infinity" | "-Infinity"; @@ -100,7 +108,11 @@ export type Int64Value = Message<"google.protobuf.Int64Value"> & { }; /** - * JSON type for the message google.protobuf.Int64Value. + * Wrapper message for `int64`. + * + * The JSON representation for `Int64Value` is JSON string. + * + * @generated from message google.protobuf.Int64Value */ export type Int64ValueJson = string; @@ -128,7 +140,11 @@ export type UInt64Value = Message<"google.protobuf.UInt64Value"> & { }; /** - * JSON type for the message google.protobuf.UInt64Value. + * Wrapper message for `uint64`. + * + * The JSON representation for `UInt64Value` is JSON string. + * + * @generated from message google.protobuf.UInt64Value */ export type UInt64ValueJson = string; @@ -156,7 +172,11 @@ export type Int32Value = Message<"google.protobuf.Int32Value"> & { }; /** - * JSON type for the message google.protobuf.Int32Value. + * Wrapper message for `int32`. + * + * The JSON representation for `Int32Value` is JSON number. + * + * @generated from message google.protobuf.Int32Value */ export type Int32ValueJson = number; @@ -184,7 +204,11 @@ export type UInt32Value = Message<"google.protobuf.UInt32Value"> & { }; /** - * JSON type for the message google.protobuf.UInt32Value. + * Wrapper message for `uint32`. + * + * The JSON representation for `UInt32Value` is JSON number. + * + * @generated from message google.protobuf.UInt32Value */ export type UInt32ValueJson = number; @@ -212,7 +236,11 @@ export type BoolValue = Message<"google.protobuf.BoolValue"> & { }; /** - * JSON type for the message google.protobuf.BoolValue. + * Wrapper message for `bool`. + * + * The JSON representation for `BoolValue` is JSON `true` and `false`. + * + * @generated from message google.protobuf.BoolValue */ export type BoolValueJson = boolean; @@ -240,7 +268,11 @@ export type StringValue = Message<"google.protobuf.StringValue"> & { }; /** - * JSON type for the message google.protobuf.StringValue. + * Wrapper message for `string`. + * + * The JSON representation for `StringValue` is JSON string. + * + * @generated from message google.protobuf.StringValue */ export type StringValueJson = string; @@ -268,7 +300,11 @@ export type BytesValue = Message<"google.protobuf.BytesValue"> & { }; /** - * JSON type for the message google.protobuf.BytesValue. + * Wrapper message for `bytes`. + * + * The JSON representation for `BytesValue` is JSON string. + * + * @generated from message google.protobuf.BytesValue */ export type BytesValueJson = string; diff --git a/packages/protoc-gen-es/src/protoc-gen-es-plugin.ts b/packages/protoc-gen-es/src/protoc-gen-es-plugin.ts index 364959c83..9ccb66e0a 100644 --- a/packages/protoc-gen-es/src/protoc-gen-es-plugin.ts +++ b/packages/protoc-gen-es/src/protoc-gen-es-plugin.ts @@ -23,7 +23,6 @@ import { embedFileDesc, pathInFileDesc } from "@bufbuild/protobuf/codegenv1"; import { isWrapperDesc } from "@bufbuild/protobuf/wkt"; import { createEcmaScriptPlugin, - getDeclarationString, type GeneratedFile, type Printable, type Schema, @@ -378,7 +377,7 @@ function generateEnumShape(f: GeneratedFile, enumeration: DescEnum) { // prettier-ignore function generateEnumJsonShape(f: GeneratedFile, enumeration: DescEnum, target: Extract) { - f.print(f.jsDoc(`JSON type for the ${enumeration.toString()}.`)); + f.print(f.jsDoc(enumeration)); const declaration = target == "ts" ? "type" : "declare type"; const values: Printable[] = []; if (enumeration.typeName == "google.protobuf.NullValue") { @@ -439,11 +438,11 @@ function generateMessageShape(f: GeneratedFile, message: DescMessage, target: Ex // prettier-ignore function generateMessageJsonShape(f: GeneratedFile, message: DescMessage, target: Extract) { const exp = f.export(target == "ts" ? "type" : "declare type", f.importJson(message).name); - f.print(f.jsDoc(`JSON type for the ${message.toString()}.`)); + f.print(f.jsDoc(message)); switch (message.typeName) { case "google.protobuf.Any": f.print(exp, " = {"); - f.print(` "@type"?: string`); + f.print(` "@type"?: string;`); f.print("};"); break; case "google.protobuf.Timestamp": @@ -475,7 +474,7 @@ function generateMessageJsonShape(f: GeneratedFile, message: DescMessage, target for (const field of message.fields) { switch (field.kind) { default: - f.print(f.jsDoc(`@generated from field: ${getDeclarationString(field)};`, " ")); + f.print(f.jsDoc(field, " ")); // eslint-disable-next-line no-case-declarations let jsonName: Printable = field.jsonName; if (jsonName === ""