Support extensions

[timostamm]

This PR adds support for extensions, a Protobuf language feature that allows to extend a message with an additional field.

Here is an example:

syntax = "proto2";
import "example.proto";
package extra;

extend example.User {
  optional uint32 age = 100;
}

The message we extend must declare a range of field numbers for extensions:

// example.proto
syntax = "proto2";
package example;

message User {
  optional string name = 1;
  extensions 100 to 200;
}

Generating code with @bufbuild/protoc-gen-es will add a new export with the name of the extension field:

/**
 * @generated from extension: optional uint32 age = 100;
 */
export declare const age: Extension<User, number>;

Using the new accessor functions for extensions introduced by this PR, the field can be set on the extended message in a type-safe way:

import { clearExtension, getExtension, hasExtension, setExtension } from "@bufbuild/protobuf";
import { User} from "./gen/example_pb.js";
import { age } from "./gen/extra_pb.js";

const user = new User();
setExtension(user, age, 123);
hasExtension(user, age); // true
getExtension(user, age); // 123
clearExtension(user, age);

Extensions are supported in the JSON format as well. Similar to google.protobuf.Any, you
have to provide a type registry to let the serializer know about extension.

Example for parsing and serializing messages with extensions.

import {createRegistry, getExtension, hasExtension} from "@bufbuild/protobuf";
import {User} from "./gen/example_pb.js";
import {age} from "./gen/extra_pb.js";

const options = {
  typeRegistry: createRegistry(age),
};

const user = User.fromJsonString(`
  {
   "name": "Joe",  
   "[extra.age]": 77 
  }
`, options);

hasExtension(user, age); // true
getExtension(user, age); // 77
user.toJsonString(options); // {"name":"Joe","[extra.age]":77}

Related changes:

• createRegistry accepts the new Extension type.
• The registries created by createRegistry and createRegistryFromDesc implement the new interface IExtensionRegistry to look up extensions.
• The typeRegistry JSON serialization option can now implement IExtensionRegistry.
• @bufbuild/protoplugin accepts DescExtension in GeneratedFile.import, GeneratedFile.print, and related methods to allow custom plugins to refer to extensions easily.

Regression checks:

• Bundle size in our benchmark increases by ~4.7%.
• There are no noticeable regressions in performance from what I could see running make perf.

A note about custom options:
You can learn more about extensions in the language guide. Note that extensions can only be used for custom options in proto3.

Currently, extensions cannot be used to retrieve custom options from generated code in Protobuf-ES, but we plan to follow up with a solution. #397 is tracking the feature. Custom options can be retrieved from descriptors, so it is possible to use them to read options in a custom plugin.

Planned follow-ups:

• Add documentation in this repository in docs/
• Deprecate the custom option accessor functions exported from @bufbuild/protoplugin/ecmascript and document how to use extensions instead.

Closes #86.

[timostamm]

Passing 100% of the protobuf v25.2 conformance tests now.

[jhump]

Very nice.

[jhump]

Extensions cannot be maps. So instead of this union, maybe have the caller (makeFieldInfo) raise an exception if it sees a DescExtension claiming to be a map?

[timostamm]

Good call, updated in eb9a200.

[jhump]

Since groups are now ostensibly supported, let's also add a group extension, to make sure they work, too. (Maybe a repeated group extension, too?)

[timostamm]

👍 added in 97b9729.

[jhump]

I take it this cannot use instanceof because the types in the union are all interfaces (vs. classes or other nominal JS types)? Unfortunate...

[timostamm]

That's correct, and I agree 😢

[jhump]

I guess the kind for group fields will be "message"? Or does this need to be expanded to include groups?

[timostamm]

Yes, a group field is kind: "message" with delimited: true. Since we generate a message class for a group, it's a decent fit. This will also work nicely with the edition feature message_encoding = DELIMITED.

[jhump]

Is it possible to also assert here that the type name of the message matches the extension's extendee? I'm thinking about possible dynamic message cases, where a concrete type E of the message is not sufficient to guarantee that the extension correctly applies to it.

[timostamm]

Good call, added an assertion for the mutating functions, but left the behavior of hasExtension as is: c1d5b71

[jhump]

A consequential downside of this approach that may need considerable documentation is that extension values are effectively read-only. So even if this returns a mutable value, mutating it has no effect on the original extended message. Instead, setExtension must always be called, even if the top-level element (like an array or object) is unchanged but its contents are being mutated. This may be counter-intuitive compared to all other kinds of field access on the message.

[timostamm]

👍 Added a comment in 5fd6e96.

I think the documentation (a follow-up to this PR) will make this clear via examples, and I'll make sure to call it out explicitly.

[jhump]

If wire type is "start group", how does this know the tag number to look for in the closing "end group" tag?

[timostamm]

It doesn't. Method skip returns the bytes until (and including) the "end group" tag. It recursively skips nested groups. We're iterating over tags we just created ourselves, so we should be fine in this case.

There is a check for matching end group field number when we parse a group here. IMO it would be better to check in method skip, so that we verify unknown fields for matching group start/end tags as well, but I'm not sure it's worth it right now, as we're already moving a lot of parts.

[jhump]

Ack. Maybe a TODO in reader.skip?

[jhump]

Were these two checks not worth keeping anywhere?

[timostamm]

These were left over from development, I forgot to remove them earlier. I expect it to very rare that users create their own extension, so we can rely on documentation and typings (makeExtension() does not allow oneof or map) here to shave off non-essential bytes from the bundle size. The assertions for the matching extendee in the accessors is a different situation, because it's very possible to pass in the wrong message without nominal typing.

[jhump]

LGTM!