protobufjs 8.2.0 → 8.3.0

package/README.md

@@ -70,7 +70,7 @@ protobuf.js converts `.proto` field names to camelCase by default, so `awesome_f
 
 ### Load a schema
 
-```js
+```ts
 const protobuf = require("protobufjs");
 
 const root = protobuf.loadSync("awesome.proto");
@@ -81,7 +81,7 @@ Use `protobuf.load()` for the asynchronous variant.
 
 ### Encode and decode
 
-```js
+```ts
 const payload = { awesomeField: "hello" };
 
 // Optionally verify if the payload is of uncertain shape
@@ -103,7 +103,7 @@ Install [`long`](https://github.com/dcodeIO/long.js) with protobuf.js when exact
 
 ### Convert plain objects
 
-```js
+```ts
 const message = AwesomeMessage.fromObject({ awesomeField: 42 });
 const object = AwesomeMessage.toObject(message, {
   longs: String,
@@ -197,7 +197,7 @@ Bundling schemas avoids reparsing `.proto` files at runtime and can reduce brows
 npx pbjs -t json -o awesome.json awesome1.proto awesome2.proto ...
 ```
 
-```js
+```ts
 const bundle = require("./awesome.json");
 
 const root = protobuf.Root.fromJSON(bundle);
@@ -208,7 +208,7 @@ const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
 npx pbjs -t json-module -w esm -o awesome.js --dts awesome.proto
 ```
 
-```js
+```ts
 import { awesomepackage } from "./awesome.js";
 
 const AwesomeMessage = awesomepackage.AwesomeMessage;
@@ -218,7 +218,45 @@ JSON modules export the reflection root and, with `-w esm`, also provide top-lev
 
 ### TypeScript integration
 
-TypeScript is a first-class target in protobuf.js. The runtime API is typed, and with `--dts`, both `json-module` and `static-module` emit ready-to-run JavaScript modules together with matching TypeScript declarations. No separate transpile step is necessary.
+protobuf.js works with TypeScript out of the box: the runtime API is typed, and generated declarations expose idiomatic TypeScript types with type-checked oneofs and JavaScript-friendly plain-object input. No separate `protoc` invocation or TypeScript transpile step is necessary.
+
+For example, given the oneof:
+
+```proto
+message Profile {
+  oneof contact {
+    string email = 1;
+    string phone = 2;
+  }
+}
+```
+
+Generated declarations narrow both the `contact` oneof and the concrete values:
+
+```ts
+const profile = Profile.create({
+  contact: "email",
+  email: "hello@example.com"
+});
+
+if (profile.contact === "email") {
+  profile.email; // string
+}
+
+const decoded = Profile.decode(bytes);
+if (decoded.phone != null) {
+  decoded.phone; // string
+}
+```
+
+Plain objects can use the same narrowed shape through a collision-free scoped type:
+
+```ts
+const object: Profile.$Shape = {
+  contact: "email",
+  email: "hello@example.com"
+};
+```
 
 ## Advanced usage
 
@@ -226,7 +264,7 @@ TypeScript is a first-class target in protobuf.js. The runtime API is typed, and
 
 The full and light builds can construct schemas directly through reflection:
 
-```js
+```ts
 const AwesomeMessage = new protobuf.Type("AwesomeMessage")
   .add(new protobuf.Field("awesomeField", 1, "string"));
 
@@ -237,30 +275,29 @@ const root = new protobuf.Root()
 
 ### Custom message classes
 
-Message classes can be extended by reusing the generated constructor:
-
-```js
-const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor;
+A reflected type can use a custom class as its runtime constructor:
 
-AwesomeMessage.customStaticMethod = function() {
-  // ...
-};
-AwesomeMessage.prototype.customInstanceMethod = function() {
-  // ...
-};
-```
+```ts
+class AwesomeMessage extends protobuf.Message<AwesomeMessage> {
+  awesomeField = "";
 
-Alternatively, a custom constructor can be registered:
+  constructor(properties?: protobuf.Properties<AwesomeMessage>) {
+    super(properties);
+    // ...
+  }
 
-```js
-function AwesomeMessage(properties) {
-  // ...
+  customInstanceMethod() {
+    return this.awesomeField.toLowerCase();
+  }
 }
 
 root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
+
+const decoded = AwesomeMessage.decode(bytes);
+decoded.customInstanceMethod(); // string
 ```
 
-Custom constructors are populated with static `create`, `encode`, `encodeDelimited`, `decode`, `decodeDelimited`, `verify`, `fromObject`, `toObject`, and the instance method `toJSON`. The reflected type is available as `AwesomeMessage.$type` and `message.$type`.
+protobuf.js will populate the constructor with the usual static runtime methods and use it for decoded messages. In TypeScript, custom members are visible when using the custom class type in consuming code.
 
 ### Services
 
@@ -278,14 +315,6 @@ Protocol Buffers [Text Format](https://protobuf.dev/reference/protobuf/textforma
 
 In [CSP](https://w3c.github.io/webappsec-csp/)-restricted environments that disallow unsafe-eval, use generated static code instead of runtime code generation.
 
-## Compatibility
-
-Supported runtimes are browsers, Node.js v12+, Deno (`deno add npm:protobufjs`) and Bun (`bun add protobufjs`). When using the CLI with Bun, Node.js must also be installed.
-
-## Security
-
-protobuf.js favors transparent disclosure. Security-impacting reports are handled through coordinated GitHub Security Advisories where appropriate. See [SECURITY.md](./SECURITY.md) for supported release lines, reporting instructions, and notes on untrusted schema input.
-
 ## Conformance
 
 protobuf.js targets full binary wire-format conformance for **Proto2**, **Proto3** and **Editions**. CI runs the official Protocol Buffers conformance suite, with logs uploaded as artifacts.
@@ -298,62 +327,71 @@ protobuf.js targets full binary wire-format conformance for **Proto2**, **Proto3
 
 ## Performance
 
-In both reflection and static modes, protobuf.js builds specialized encoders and decoders for each message type instead of interpreting descriptors at runtime.
+In both reflection and static modes, protobuf.js builds specialized encoders and decoders instead of interpreting descriptors at runtime.
 
-The repository includes a small benchmark for the bundled fixture in [`bench/`](./bench/). It compares protobuf.js reflection and static code against native `JSON.stringify`/`JSON.parse` and [google-protobuf](https://www.npmjs.com/package/google-protobuf) (`protoc-gen-js`). Results depend on hardware, Node.js version, and the message shape, so they should be treated as indicative rather than absolute.
+The repository includes a [small benchmark](./bench). It compares protobuf.js reflection and static code against JSON encode/decode, protoc-gen-js, and protoc-gen-es. Results depend on hardware, Node.js version, and message shape, so they should be treated as indicative rather than absolute.
 
-One run on an AMD Ryzen 9 9950X3D with Node.js 24.13.0 and google-protobuf 4.0.2 produced:
+One run on an AMD Ryzen 9 9950X3D with Node.js 24.15.0 produced:
 
 ```
-benchmarking encoding performance ...
-
-protobuf.js (reflect) x 2,492,315 ops/sec ±0.56% (94 runs sampled)
-protobuf.js (static) x 2,316,421 ops/sec ±0.49% (96 runs sampled)
-JSON (string) x 2,581,565 ops/sec ±0.22% (99 runs sampled)
-JSON (buffer) x 2,086,216 ops/sec ±0.68% (92 runs sampled)
-google-protobuf x 1,052,145 ops/sec ±0.24% (101 runs sampled)
-
-          JSON (string) was fastest
-  protobuf.js (reflect) was 3.8% ops/sec slower (factor 1.0)
-   protobuf.js (static) was 10.5% ops/sec slower (factor 1.1)
-          JSON (buffer) was 19.6% ops/sec slower (factor 1.2)
-        google-protobuf was 59.3% ops/sec slower (factor 2.5)
-
-benchmarking decoding performance ...
-
-protobuf.js (reflect) x 6,053,370 ops/sec ±0.25% (98 runs sampled)
-protobuf.js (static) x 6,081,190 ops/sec ±0.35% (97 runs sampled)
-JSON (string) x 1,579,677 ops/sec ±0.11% (100 runs sampled)
-JSON (buffer) x 1,383,484 ops/sec ±0.15% (98 runs sampled)
-google-protobuf x 931,575 ops/sec ±0.25% (97 runs sampled)
-
-   protobuf.js (static) was fastest
-  protobuf.js (reflect) was 0.4% ops/sec slower (factor 1.0)
-          JSON (string) was 74.0% ops/sec slower (factor 3.8)
-          JSON (buffer) was 77.2% ops/sec slower (factor 4.4)
-        google-protobuf was 84.7% ops/sec slower (factor 6.5)
-
-benchmarking combined performance ...
-
-protobuf.js (reflect) x 1,259,417 ops/sec ±0.33% (101 runs sampled)
-protobuf.js (static) x 1,296,628 ops/sec ±0.20% (98 runs sampled)
-JSON (string) x 848,422 ops/sec ±0.10% (100 runs sampled)
-JSON (buffer) x 727,866 ops/sec ±0.30% (100 runs sampled)
-google-protobuf x 477,041 ops/sec ±0.22% (101 runs sampled)
-
-   protobuf.js (static) was fastest
-  protobuf.js (reflect) was 3.0% ops/sec slower (factor 1.0)
-          JSON (string) was 34.5% ops/sec slower (factor 1.5)
-          JSON (buffer) was 43.9% ops/sec slower (factor 1.8)
-        google-protobuf was 63.2% ops/sec slower (factor 2.7)
+benchmarking encode performance ...
+
+protobuf.js reflect x 2,430,103 ops/sec ±0.62% (95 runs sampled)
+protobuf.js static x 2,390,407 ops/sec ±0.42% (96 runs sampled)
+JSON encode x 2,155,918 ops/sec ±0.63% (92 runs sampled)
+protoc-gen-js x 995,429 ops/sec ±0.18% (98 runs sampled)
+protoc-gen-es x 403,334 ops/sec ±0.14% (96 runs sampled)
+
+    protobuf.js reflect was fastest
+     protobuf.js static was 1.4% ops/sec slower (factor 1.0)
+            JSON encode was 11.3% ops/sec slower (factor 1.1)
+          protoc-gen-js was 58.9% ops/sec slower (factor 2.4)
+          protoc-gen-es was 83.3% ops/sec slower (factor 6.0)
+
+benchmarking decode performance ...
+
+protobuf.js reflect x 6,440,387 ops/sec ±0.25% (97 runs sampled)
+protobuf.js static x 6,463,283 ops/sec ±0.27% (101 runs sampled)
+JSON decode x 1,409,923 ops/sec ±0.11% (97 runs sampled)
+protoc-gen-js x 947,647 ops/sec ±0.15% (99 runs sampled)
+protoc-gen-es x 731,819 ops/sec ±0.28% (98 runs sampled)
+
+     protobuf.js static was fastest
+    protobuf.js reflect was 0.3% ops/sec slower (factor 1.0)
+            JSON decode was 78.2% ops/sec slower (factor 4.6)
+          protoc-gen-js was 85.3% ops/sec slower (factor 6.8)
+          protoc-gen-es was 88.7% ops/sec slower (factor 8.8)
+
+benchmarking round-trip performance ...
+
+protobuf.js reflect x 1,310,677 ops/sec ±0.21% (97 runs sampled)
+protobuf.js static x 1,310,926 ops/sec ±0.26% (101 runs sampled)
+JSON encode/decode x 741,714 ops/sec ±0.24% (99 runs sampled)
+protoc-gen-js x 472,844 ops/sec ±0.09% (96 runs sampled)
+protoc-gen-es x 254,044 ops/sec ±0.05% (101 runs sampled)
+
+    protobuf.js reflect was fastest
+     protobuf.js static was 0.0% ops/sec slower (factor 1.0)
+     JSON encode/decode was 43.4% ops/sec slower (factor 1.8)
+          protoc-gen-js was 63.9% ops/sec slower (factor 2.8)
+          protoc-gen-es was 80.6% ops/sec slower (factor 5.2)
 ```
 
 Run it locally with:
 
 ```sh
+npm --prefix bench install
 npm run bench
 ```
 
+## Compatibility
+
+Supported runtimes are browsers, Node.js v12+, Deno and Bun. When using the CLI with Bun, Node.js must also be installed.
+
+## Security
+
+protobuf.js favors transparent disclosure. Security-impacting reports are handled through coordinated GitHub Security Advisories where appropriate. See [SECURITY.md](./SECURITY.md) for supported release lines, reporting instructions, and notes on untrusted schema input.
+
 ## Development
 
 ```sh