@openclaw/diagnostics-otel 2026.7.2-beta.7 → 2026.7.33

package/node_modules/@opentelemetry/sdk-node/node_modules/protobufjs/README.md

@@ -9,432 +9,719 @@
 
 **Protocol Buffers** are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google ([see](https://protobuf.dev/)).
 
-**protobuf.js** is a very fast, conformant, and unusually versatile JavaScript implementation of Protocol Buffers for Node.js and browsers. It works with `.proto` files out of the box, does not require protoc, and supports runtime reflection as well as specialized code generation with strong TypeScript declarations.
+**protobuf.js** is a pure JavaScript implementation with [TypeScript](https://www.typescriptlang.org) support for [Node.js](https://nodejs.org) and the browser. It's easy to use, does not sacrifice on performance, has good conformance and works out of the box with [.proto](https://protobuf.dev/programming-guides/proto3/) files!
 
-If protobuf.js is important to your project or organization, or if you depend on it commercially, [consider supporting](https://github.com/sponsors/dcodeIO) its ongoing maintenance. Sponsorship helps make bug fixes, releases, LTS/security handling, and user support more sustainable.
+Contents
+--------
 
-## Getting started
+* [Installation](#installation)<br />
+  How to include protobuf.js in your project.
 
-Getting up and running is simple: Install the package, load a `.proto` file, and you are all set to encode and decode Protobuf messages. From there, protobuf.js grows with your requirements: Add any combination of capabilities, such as [code generation](#code-generation), [TypeScript declarations](#typescript-integration), [transport-agnostic services](#services), [programmatic schemas](#programmatic-schemas), [optional extensions](#extensions), and more as needed. All in one flexible toolkit.
+* [Usage](#usage)<br />
+  A brief introduction to using the toolset.
 
-### Install
+  * [Valid Message](#valid-message)
+  * [Toolset](#toolset)<br />
+
+* [Examples](#examples)<br />
+  A few examples to get you started.
+
+  * [Using .proto files](#using-proto-files)
+  * [Using JSON descriptors](#using-json-descriptors)
+  * [Using reflection only](#using-reflection-only)
+  * [Using custom classes](#using-custom-classes)
+  * [Using services](#using-services)
+  * [Usage with TypeScript](#usage-with-typescript)<br />
+
+* [Additional documentation](#additional-documentation)<br />
+  A list of available documentation resources.
+
+* [Performance](#performance)<br />
+  A few internals and a benchmark on performance.
+
+* [Compatibility](#compatibility)<br />
+  Notes on compatibility regarding browsers and optional libraries.
+
+* [Building](#building)<br />
+  How to build the library and its components yourself.
+
+Installation
+---------------
+
+### Node.js
 
 ```sh
-npm install protobufjs
+npm install protobufjs --save
 ```
 
-The [command line utility](./cli/#readme) for generating reflection bundles, static code and TypeScript declarations is published as an add-on package:
+```js
+// Static code + Reflection + .proto parser
+var protobuf = require("protobufjs");
+
+// Static code + Reflection
+var protobuf = require("protobufjs/light");
+
+// Static code only
+var protobuf = require("protobufjs/minimal");
+```
+
+The optional [command line utility](./cli/) to generate static code and reflection bundles lives in the `protobufjs-cli` package and can be installed separately:
 
 ```sh
-npm install --save-dev protobufjs-cli
+npm install protobufjs-cli --save-dev
 ```
 
-The CLI is a JS-native protobuf.js toolchain that does not require setting up `protoc`. If you prefer a `protoc`-based workflow, it provides `protoc-gen-pbjs` as an option.
+### Browsers
 
-#### Browser builds
+Pick the variant matching your needs and replace the version tag with the exact [release](https://github.com/protobufjs/protobuf.js/tags) your project depends upon. For example, to use the minified full variant:
 
-Canonical browser builds for each runtime variant are [provided via the jsDelivr CDN](https://cdn.jsdelivr.net/npm/protobufjs@8.X.X/dist/), supporting CommonJS, AMD and global `window.protobuf`. Make sure to pin an exact version in production.
+```html
+<script src="//cdn.jsdelivr.net/npm/protobufjs@7.X.X/dist/protobuf.min.js"></script>
+```
 
-## Usage
+| Distribution | Location
+|--------------|--------------------------------------------------------
+| Full         | <https://cdn.jsdelivr.net/npm/protobufjs/dist/>
+| Light        | <https://cdn.jsdelivr.net/npm/protobufjs/dist/light/>
+| Minimal      | <https://cdn.jsdelivr.net/npm/protobufjs/dist/minimal/>
 
-The examples below use this schema:
+All variants support CommonJS and AMD loaders and export globally as `window.protobuf`.
 
-```proto
-syntax = "proto3";
+Usage
+-----
 
-package awesomepackage;
+Because JavaScript is a dynamically typed language, protobuf.js utilizes the concept of a **valid message** in order to provide the best possible [performance](#performance) (and, as a side product, proper typings):
 
-message AwesomeMessage {
-  string awesome_field = 1;
-}
-```
+### Valid message
 
-protobuf.js converts `.proto` field names to camelCase by default, so `awesome_field` is used as `awesomeField` in JavaScript. Use the `keepCase` option when loading or parsing `.proto` files to preserve field names as written.
+> A valid message is an object (1) not missing any required fields and (2) exclusively composed of JS types understood by the wire format writer.
 
-### Load a schema
+There are two possible types of valid messages and the encoder is able to work with both of these for convenience:
 
-```ts
-const protobuf = require("protobufjs");
+* **Message instances** (explicit instances of message classes with default values on their prototype) naturally satisfy the requirements of a valid message and
+* **Plain JavaScript objects** that just so happen to be composed in a way satisfying the requirements of a valid message as well.
 
-const root = await protobuf.load("awesome.proto");
-const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
-```
+In a nutshell, the wire format writer understands the following types:
 
-Optionally use `load()` with a callback, or `loadSync()` for synchronous loading on Node.js. Imports resolve relative to the importing file by default. To resolve imports against a specific base directory, create a `Root` and override `root.resolvePath` before calling `root.load()`.
+| Field type | Expected JS type (create, encode) | Conversion (fromObject)
+|------------|-----------------------------------|------------------------
+| s-/u-/int32<br />s-/fixed32 | `number` (32 bit integer) | <code>value &#124; 0</code> if signed<br />`value >>> 0` if unsigned
+| s-/u-/int64<br />s-/fixed64 | `Long`-like (optimal)<br />`number` (53 bit integer) | `Long.fromValue(value)` with long.js<br />`parseInt(value, 10)` otherwise
+| float<br />double | `number` | `Number(value)`
+| bool | `boolean` | `Boolean(value)`
+| string | `string` | `String(value)`
+| bytes | `Uint8Array` (optimal)<br />`Buffer` (optimal under node)<br />`Array.<number>` (8 bit integers) | `base64.decode(value)` if a `string`<br />`Object` with non-zero `.length` is assumed to be buffer-like
+| enum | `number` (32 bit integer) | Looks up the numeric id if a `string`
+| message | Valid message | `Message.fromObject(value)`
+| repeated T | `Array<T>` | Copy
+| map<K, V> | `Object<K,V>` | Copy
 
-### Encode and decode
+* Explicit `undefined` and `null` are considered as not set if the field is optional.
+* Maps are objects where the key is the string representation of the respective value or an 8 characters long hash string for `Long`-likes.
 
-```ts
-const payload = { awesomeField: "hello" };
+### Toolset
+
+With that in mind and again for performance reasons, each message class provides a distinct set of methods with each method doing just one thing. This avoids unnecessary assertions / redundant operations where performance is a concern but also forces a user to perform verification (of plain JavaScript objects that *might* just so happen to be a valid message) explicitly where necessary - for example when dealing with user input.
+
+**Note** that `Message` below refers to any message class.
+
+* **Message.verify**(message: `Object`): `null|string`<br />
+  verifies that a **plain JavaScript object** satisfies the requirements of a valid message and thus can be encoded without issues. Instead of throwing, it returns the error message as a string, if any.
+
+  ```js
+  var payload = "invalid (not an object)";
+  var err = AwesomeMessage.verify(payload);
+  if (err)
+    throw Error(err);
+  ```
+
+* **Message.encode**(message: `Message|Object` [, writer: `Writer`]): `Writer`<br />
+  encodes a **message instance** or valid **plain JavaScript object**. This method does not implicitly verify the message and it's up to the user to make sure that the payload is a valid message.
+
+  ```js
+  var buffer = AwesomeMessage.encode(message).finish();
+  ```
+
+* **Message.encodeDelimited**(message: `Message|Object` [, writer: `Writer`]): `Writer`<br />
+  works like `Message.encode` but additionally prepends the length of the message as a varint.
+
+* **Message.decode**(reader: `Reader|Uint8Array`): `Message`<br />
+  decodes a buffer to a **message instance**. If required fields are missing, it throws a `util.ProtocolError` with an `instance` property set to the so far decoded message. If the wire format is invalid, it throws an `Error`.
+
+  ```js
+  try {
+    var decodedMessage = AwesomeMessage.decode(buffer);
+  } catch (e) {
+      if (e instanceof protobuf.util.ProtocolError) {
+        // e.instance holds the so far decoded message with missing required fields
+      } else {
+        // wire format is invalid
+      }
+  }
+  ```
+
+* **Message.decodeDelimited**(reader: `Reader|Uint8Array`): `Message`<br />
+  works like `Message.decode` but additionally reads the length of the message prepended as a varint.
+
+* **Message.create**(properties: `Object`): `Message`<br />
+  creates a new **message instance** from a set of properties that satisfy the requirements of a valid message. Where applicable, it is recommended to prefer `Message.create` over `Message.fromObject` because it doesn't perform possibly redundant conversion.
+
+  ```js
+  var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });
+  ```
+
+* **Message.fromObject**(object: `Object`): `Message`<br />
+  converts any non-valid **plain JavaScript object** to a **message instance** using the conversion steps outlined within the table above.
+
+  ```js
+  var message = AwesomeMessage.fromObject({ awesomeField: 42 });
+  // converts awesomeField to a string
+  ```
+
+* **Message.toObject**(message: `Message` [, options: `ConversionOptions`]): `Object`<br />
+  converts a **message instance** to an arbitrary **plain JavaScript object** for interoperability with other libraries or storage. The resulting plain JavaScript object *might* still satisfy the requirements of a valid message depending on the actual conversion options specified, but most of the time it does not.
+
+  ```js
+  var object = AwesomeMessage.toObject(message, {
+    enums: String,  // enums as string names
+    longs: String,  // longs as strings (or BigInt for bigint values)
+    bytes: String,  // bytes as base64 encoded strings
+    defaults: true, // includes default values
+    arrays: true,   // populates empty arrays (repeated fields) even if defaults=false
+    objects: true,  // populates empty objects (map fields) even if defaults=false
+    oneofs: true    // includes virtual oneof fields set to the present field's name
+  });
+  ```
+
+For reference, the following diagram aims to display relationships between the different methods and the concept of a valid message:
 
-// Optionally create a message instance from already valid data
-const message = AwesomeMessage.create(payload);
+<p align="center"><img alt="Toolset Diagram" src="https://protobufjs.github.io/protobuf.js/toolset.svg" /></p>
 
-const encoded = AwesomeMessage.encode(message).finish();
-const decoded = AwesomeMessage.decode(encoded);
+> In other words: `verify` indicates that calling `create` or `encode` directly on the plain object will [result in a valid message respectively] succeed. `fromObject`, on the other hand, does conversion from a broader range of plain objects to create valid messages. ([ref](https://github.com/protobufjs/protobuf.js/issues/748#issuecomment-291925749))
+
+Examples
+--------
+
+### Using .proto files
+
+It is possible to load existing .proto files using the full library, which parses and compiles the definitions to ready to use (reflection-based) message classes:
+
+```protobuf
+// awesome.proto
+package awesomepackage;
+syntax = "proto3";
+
+message AwesomeMessage {
+    string awesome_field = 1; // becomes awesomeField
+}
 ```
 
-`encode` expects a message instance or equivalent plain object and does not verify input implicitly. Use `create` to create a message instance from already valid data when useful, `verify` for plain objects whose shape is not guaranteed, and `fromObject` when conversion from broader JavaScript objects is needed.
+```js
+protobuf.load("awesome.proto", function(err, root) {
+    if (err)
+        throw err;
 
-Plain objects can be encoded directly when they already use protobuf.js runtime types: numbers for 32-bit numeric fields, booleans for `bool`, strings for `string`, `Uint8Array` or `Buffer` for `bytes`, arrays for repeated fields, and plain objects for maps. Map keys are the string representation of the respective value or an 8-character hash string for 64-bit keys.
+    // Obtain a message type
+    var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
 
-Unknown fields present on the wire are discarded by default. To preserve and forward unknown fields, set `reader.discardUnknown = false` before decoding with that reader, or make this the default for subsequently created readers with `Reader.discardUnknown = false`. Preserved unknown field data can be dropped from a decoded message with `delete message.$unknowns`.
+    // Exemplary payload
+    var payload = { awesomeField: "AwesomeString" };
 
-### Convert plain objects
+    // Verify the payload if necessary (i.e. when possibly incomplete or invalid)
+    var errMsg = AwesomeMessage.verify(payload);
+    if (errMsg)
+        throw Error(errMsg);
 
-Conversion is an explicit interoperability boundary. `fromObject` accepts common JavaScript inputs such as enum values by name, base64 bytes, decimal 64-bit strings, `Long`, and `BigInt`; `toObject` lets callers choose the output expected by their application or transport.
+    // Create a new message
+    var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary
 
-```ts
-const message = AwesomeMessage.fromObject({ awesomeField: 42 });
-const object = AwesomeMessage.toObject(message, {
-  longs: String,
-  enums: String,
-  bytes: String
+    // Encode a message to an Uint8Array (browser) or Buffer (node)
+    var buffer = AwesomeMessage.encode(message).finish();
+    // ... do something with buffer
+
+    // Decode an Uint8Array (browser) or Buffer (node) to a message
+    var message = AwesomeMessage.decode(buffer);
+    // ... do something with message
+
+    // If the application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited.
+
+    // Maybe convert the message back to a plain object
+    var object = AwesomeMessage.toObject(message, {
+        longs: String,
+        enums: String,
+        bytes: String,
+        // see ConversionOptions
+    });
 });
 ```
 
-Common `ConversionOptions` are:
+Additionally, promise syntax can be used by omitting the callback, if preferred:
 
-| Option | Effect |
-|--------|--------|
-| `longs: BigInt` | Converts 64-bit values to bigint values |
-| `longs: String` | Converts 64-bit values to decimal strings |
-| `longs: Number` | Converts 64-bit values to JS numbers (may lose precision) |
-| `enums: String` | Converts enum values to names |
-| `bytes: String` | Converts bytes to base64 strings |
-| `defaults: true` | Includes default values for unset fields |
-| `arrays: true` | Includes empty arrays for repeated fields |
-| `objects: true` | Includes empty objects for map fields |
-| `oneofs: true` | Includes virtual oneof discriminator properties |
+```js
+protobuf.load("awesome.proto")
+    .then(function(root) {
+       ...
+    });
+```
 
-## Message API
+### Using JSON descriptors
+
+The library utilizes JSON descriptors that are equivalent to a .proto definition. For example, the following is identical to the .proto definition seen above:
+
+```json
+// awesome.json
+{
+  "nested": {
+    "awesomepackage": {
+      "nested": {
+        "AwesomeMessage": {
+          "fields": {
+            "awesomeField": {
+              "type": "string",
+              "id": 1
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
 
-Message types expose focused methods for validation, conversion, and binary I/O.
+JSON descriptors closely resemble the internal reflection structure:
 
-* **encode**(message: `Message | object`, writer?: `Writer`): `Writer`  
-  Encodes a message or equivalent plain object. Call `.finish()` on the returned writer to obtain a buffer.
+| Type (T)           | Extends            | Type-specific properties
+|--------------------|--------------------|-------------------------
+| *ReflectionObject* |                    | options
+| *Namespace*        | *ReflectionObject* | nested
+| Root               | *Namespace*        | **nested**
+| Type               | *Namespace*        | **fields**
+| Enum               | *ReflectionObject* | **values**
+| Field              | *ReflectionObject* | rule, **type**, **id**
+| MapField           | Field              | **keyType**
+| OneOf              | *ReflectionObject* | **oneof** (array of field names)
+| Service            | *Namespace*        | **methods**
+| Method             | *ReflectionObject* | type, **requestType**, **responseType**, requestStream, responseStream
 
-* **encodeDelimited**(message: `Message | object`, writer?: `Writer`): `Writer`  
-  Encodes a length-delimited message.
+* **Bold properties** are required. *Italic types* are abstract.
+* `T.fromJSON(name, json)` creates the respective reflection object from a JSON descriptor
+* `T#toJSON()` creates a JSON descriptor from the respective reflection object (its name is used as the key within the parent)
 
-* **decode**(reader: `Reader | Uint8Array`): `Message`  
-  Decodes a message from protobuf binary data.
+Exclusively using JSON descriptors instead of .proto files enables the use of just the light library (the parser isn't required in this case).
 
-* **decodeDelimited**(reader: `Reader | Uint8Array`): `Message`  
-  Decodes a length-delimited message.
+A JSON descriptor can either be loaded the usual way:
 
-* **create**(properties?: `object`): `Message`  
-  Creates a message instance from already valid data.
+```js
+protobuf.load("awesome.json", function(err, root) {
+    if (err) throw err;
 
-* **verify**(object: `object`): `null | string`  
-  Checks whether a plain object can be encoded as-is. Returns `null` if valid, otherwise an error message.
+    // Continue at "Obtain a message type" above
+});
+```
 
-* **fromObject**(object: `object`): `Message`  
-  Converts broader JavaScript input into a message instance.
+Or it can be loaded inline:
 
-* **toObject**(message: `Message`, options?: `ConversionOptions`): `object`  
-  Converts a message instance to a configurable plain JavaScript object.
+```js
+var jsonDescriptor = require("./awesome.json"); // exemplary for node
 
-* **message.toJSON**(): `object`  
-  Converts a message instance to JSON-compatible output using default conversion options.
+var root = protobuf.Root.fromJSON(jsonDescriptor);
 
-Message instances provide runtime identity, so they can be tested with `instanceof`. Their `toJSON` method integrates them with `JSON.stringify`.
+// Continue at "Obtain a message type" above
+```
 
-Length-delimited methods read and write a varint byte length before the message, which is useful for streams and framed protocols.
+### Using reflection only
 
-If required fields are missing while decoding proto2 data, `decode` throws `protobuf.util.ProtocolError` with the partially decoded message available as `err.instance`.
+Both the full and the light library include full reflection support. One could, for example, define the .proto definitions seen in the examples above using just reflection:
 
-## Runtimes
+```js
+...
+var Root  = protobuf.Root,
+    Type  = protobuf.Type,
+    Field = protobuf.Field;
 
-protobuf.js provides three runtime entry points, keeping parser and reflection support optional: Runtime `.proto` loading needs the parser, JSON/reflection bundles need reflection support, and generated static modules only need the minimal runtime.
+var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string"));
 
-| Import                  | Includes           | Use when
-| ----------------------- | ------------------ | --------
-| `protobufjs`            | Reflection, Parser | You load `.proto` files at runtime
-| `protobufjs/light.js`   | Reflection         | You load JSON bundles or build schemas programmatically
-| `protobufjs/minimal.js` | Static runtime     | You use generated static code
+var root = new Root().define("awesomepackage").add(AwesomeMessage);
 
-The full build includes the light build, and the light build includes the minimal runtime.
+// Continue at "Create a new message" above
+...
+```
 
-## Code generation
+Detailed information on the reflection structure is available within the [API documentation](#additional-documentation).
 
-Use [`protobufjs-cli`](./cli/#readme) to generate reflection bundles, static JavaScript code, and matching TypeScript declarations, either directly with `pbjs` or through the optional `protoc-gen-pbjs` plugin for `protoc`.
+### Using custom classes
 
-Reflection keeps schemas as JSON metadata and generates optimized functions at runtime. Static code emits schema-specific, reflection-free functions ahead of time. The main tradeoffs are how schemas are loaded, how bundle size scales with schema size, and whether reflection metadata should remain available at runtime.
+Message classes can also be extended with custom functionality and it is also possible to register a custom constructor with a reflected message type:
 
-| Target | Output | Minimum Runtime |
-|--------|--------|-----------------|
-| `json` | JSON bundle | `protobufjs/light.js` |
-| `json-module` | JSON bundle module | `protobufjs/light.js` |
-| `static-module` | Static code module | `protobufjs/minimal.js` |
+```js
+...
 
-Module targets support `--wrap default` for CommonJS and AMD, plus `esm`, `commonjs`, `amd`, and `closure`; `--wrap` can also load a custom wrapper module.
+// Define a custom constructor
+function AwesomeMessage(properties) {
+    // custom initialization code
+    ...
+}
 
-### Static modules
+// Register the custom constructor with its reflected type (*)
+root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
 
-Static modules emit dedicated JavaScript for your schema, so they only need `protobufjs/minimal.js` at runtime.
+// Define custom functionality
+AwesomeMessage.customStaticMethod = function() { ... };
+AwesomeMessage.prototype.customInstanceMethod = function() { ... };
 
-```sh
-npx pbjs -t static-module -w esm -o awesome.js --dts awesome.proto
+// Continue at "Create a new message" above
 ```
 
-```ts
-import { awesomepackage } from "./awesome.js";
+(*) Besides referencing its reflected type through `AwesomeMessage.$type` and `AwesomeMesage#$type`, the respective custom class is automatically populated with:
 
-const message = awesomepackage.AwesomeMessage.create({ awesomeField: "hello" });
-```
+* `AwesomeMessage.create`
+* `AwesomeMessage.encode` and `AwesomeMessage.encodeDelimited`
+* `AwesomeMessage.decode` and `AwesomeMessage.decodeDelimited`
+* `AwesomeMessage.verify`
+* `AwesomeMessage.fromObject`, `AwesomeMessage.toObject` and `AwesomeMessage#toJSON`
 
-While static code is verbose by design, its repeated patterns compress well with Brotli or gzip, and it works in [CSP](https://w3c.github.io/webappsec-csp/)-restricted environments that disallow unsafe-eval without sacrificing performance.
+Afterwards, decoded messages of this type are `instanceof AwesomeMessage`.
 
-### Reflection bundles
+Alternatively, it is also possible to reuse and extend the internal constructor if custom initialization code is not required:
 
-Reflection bundles store schemas as compact JSON metadata, avoiding `.proto` parsing at runtime and letting browsers load schema metadata in one request. While they require at least `protobufjs/light.js`, large schemas can produce smaller combined bundles than equivalent static modules because common code is shared through reflection.
+```js
+...
 
-```sh
-npx pbjs -t json -o awesome.json awesome1.proto awesome2.proto ...
-```
+// Reuse the internal constructor
+var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor;
 
-```ts
-const bundle = require("./awesome.json");
+// Define custom functionality
+AwesomeMessage.customStaticMethod = function() { ... };
+AwesomeMessage.prototype.customInstanceMethod = function() { ... };
 
-const root = protobuf.Root.fromJSON(bundle);
-const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
+// Continue at "Create a new message" above
 ```
 
-```sh
-npx pbjs -t json-module -w esm -o awesome.js --dts awesome.proto
+### Using services
+
+The library also supports consuming services but it doesn't make any assumptions about the actual transport channel. Instead, a user must provide a suitable RPC implementation, which is an asynchronous function that takes the reflected service method, the binary request and a node-style callback as its parameters:
+
+```js
+function rpcImpl(method, requestData, callback) {
+    // perform the request using an HTTP request or a WebSocket for example
+    var responseData = ...;
+    // and call the callback with the binary response afterwards:
+    callback(null, responseData);
+}
 ```
 
+Below is a working example with a typescript implementation using grpc npm package.
 ```ts
-import { awesomepackage } from "./awesome.js";
-
-const AwesomeMessage = awesomepackage.AwesomeMessage;
+const grpc = require('grpc')
+
+const Client = grpc.makeGenericClientConstructor({})
+const client = new Client(
+  grpcServerUrl,
+  grpc.credentials.createInsecure()
+)
+
+const rpcImpl = function(method, requestData, callback) {
+  client.makeUnaryRequest(
+    method.name,
+    arg => arg,
+    arg => arg,
+    requestData,
+    callback
+  )
+}
 ```
 
-JSON modules export the reflection root and, with `-w esm`, also provide top-level named exports that align with static modules. Their declarations mirror `static-module` typings, but because JSON modules are backed by reflection objects, message instances should be created with `MyMessage.create(...)` instead of constructors. Code using `create(...)` works with static modules as well.
+Example:
 
-### TypeScript integration
+```protobuf
+// greeter.proto
+syntax = "proto3";
 
-protobuf.js works with TypeScript out of the box: the runtime API is typed, and generated JavaScript can be paired with strong TypeScript declarations in the same CLI invocation. Generated output is directly usable from JavaScript without a transpile step, and strongly typed in TypeScript projects, with type-checked oneofs and JavaScript-friendly plain-object input.
+service Greeter {
+    rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
 
-For example, given the oneof:
+message HelloRequest {
+    string name = 1;
+}
 
-```proto
-message Profile {
-  oneof contact {
-    string email = 1;
-    string phone = 2;
-  }
+message HelloReply {
+    string message = 1;
 }
 ```
 
-Generated declarations narrow both the `contact` oneof and the concrete values:
+```js
+...
+var Greeter = root.lookup("Greeter");
+var greeter = Greeter.create(/* see above */ rpcImpl, /* request delimited? */ false, /* response delimited? */ false);
 
-```ts
-const profile = Profile.create({
-  contact: "email",
-  email: "hello@example.com"
+greeter.sayHello({ name: 'you' }, function(err, response) {
+    console.log('Greeting:', response.message);
 });
+```
 
-if (profile.contact === "email") {
-  profile.email; // string
-}
+Services also support promises:
 
-const decoded = Profile.decode(bytes);
-if (decoded.contact === "phone") {
-  decoded.phone; // string
-}
+```js
+greeter.sayHello({ name: 'you' })
+    .then(function(response) {
+        console.log('Greeting:', response.message);
+    });
 ```
 
-Plain objects can use the same narrowed shape through a collision-free scoped type:
+There is also an [example for streaming RPC](https://github.com/protobufjs/protobuf.js/blob/master/examples/streaming-rpc.js).
 
-```ts
-const object: Profile.$Shape = {
-  contact: "email",
-  email: "hello@example.com"
-};
-```
+Note that the service API is meant for clients. Implementing a server-side endpoint pretty much always requires transport channel (i.e. http, websocket, etc.) specific code with the only common denominator being that it decodes and encodes messages.
+
+### Usage with TypeScript
 
-## Advanced usage
+The library ships with its own [type definitions](https://github.com/protobufjs/protobuf.js/blob/master/index.d.ts) and modern editors like [Visual Studio Code](https://code.visualstudio.com/) will automatically detect and use them for code completion.
 
-### Programmatic schemas
+The npm package depends on [@types/node](https://www.npmjs.com/package/@types/node) because of `Buffer` and [@types/long](https://www.npmjs.com/package/@types/long) because of `Long`. If you are not building for node and/or not using long.js, it should be safe to exclude them manually.
 
-The full and light builds can construct schemas directly through reflection:
+#### Using the JS API
+
+The API shown above works pretty much the same with TypeScript. However, because everything is typed, accessing fields on instances of dynamically generated message classes requires either using bracket-notation (i.e. `message["awesomeField"]`) or explicit casts. Alternatively, it is possible to use a [typings file generated for its static counterpart](#pbts-for-typescript).
 
 ```ts
-const AwesomeMessage = new protobuf.Type("AwesomeMessage")
-  .add(new protobuf.Field("awesomeField", 1, "string"));
+import { load } from "protobufjs"; // respectively "./node_modules/protobufjs"
+
+load("awesome.proto", function(err, root) {
+  if (err)
+    throw err;
 
-const root = new protobuf.Root()
-  .define("awesomepackage")
-  .add(AwesomeMessage);
+  // example code
+  const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
+
+  let message = AwesomeMessage.create({ awesomeField: "hello" });
+  console.log(`message = ${JSON.stringify(message)}`);
+
+  let buffer = AwesomeMessage.encode(message).finish();
+  console.log(`buffer = ${Array.prototype.toString.call(buffer)}`);
+
+  let decoded = AwesomeMessage.decode(buffer);
+  console.log(`decoded = ${JSON.stringify(decoded)}`);
+});
 ```
 
-### Custom message classes
+#### Using generated static code
 
-A reflected type can use a custom class as its runtime constructor:
+If you generated static code to `bundle.js` using the CLI and its type definitions to `bundle.d.ts`, then you can just do:
 
 ```ts
-class AwesomeMessage extends protobuf.Message<AwesomeMessage> {
-  awesomeField = "";
+import { AwesomeMessage } from "./bundle.js";
 
-  constructor(properties?: protobuf.Properties<AwesomeMessage>) {
-    super(properties);
-    // ...
-  }
+// example code
+let message = AwesomeMessage.create({ awesomeField: "hello" });
+let buffer  = AwesomeMessage.encode(message).finish();
+let decoded = AwesomeMessage.decode(buffer);
+```
 
-  customInstanceMethod() {
-    return this.awesomeField.toLowerCase();
-  }
-}
+#### Using decorators
 
-root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
+The library also includes an early implementation of [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
 
-const decoded = AwesomeMessage.decode(bytes);
-decoded.customInstanceMethod(); // string
-```
+**Note** that decorators are an experimental feature in TypeScript and that declaration order is important depending on the JS target. For example, `@Field.d(2, AwesomeArrayMessage)` requires that `AwesomeArrayMessage` has been defined earlier when targeting `ES5`.
 
-protobuf.js will populate the constructor with the usual static runtime methods and use it for decoded messages. When assigning constructors manually, add the type to its parent namespace/root first if fields reference other reflected types. In TypeScript, custom members are visible when using the custom class type in consuming code.
+```ts
+import { Message, Type, Field, OneOf } from "protobufjs/light"; // respectively "./node_modules/protobufjs/light.js"
 
-### Services
+export class AwesomeSubMessage extends Message<AwesomeSubMessage> {
 
-protobuf.js supports service clients built from service definitions. The service API is transport-agnostic: provide an `rpcImpl` function to connect it to HTTP, WebSocket, gRPC, or another transport.
+  @Field.d(1, "string")
+  public awesomeString: string;
 
-```js
-function myRpcImpl(method, requestData, callback) {
-  // method.name
-  // method.path
-  // method.requestStream?
-  // method.responseStream?
-  performRequest(requestData, function(err, responseData) {
-    callback(err, responseData);
-  });
 }
 
-const myService = MyService.create(myRpcImpl/*, requestDelimited?, responseDelimited? */);
-```
+export enum AwesomeEnum {
+  ONE = 1,
+  TWO = 2
+}
 
-See [examples/streaming-rpc.js](./examples/streaming-rpc.js) for a streaming example.
+@Type.d("SuperAwesomeMessage")
+export class AwesomeMessage extends Message<AwesomeMessage> {
 
-Integration example with [@grpc/grpc-js](https://www.npmjs.com/package/@grpc/grpc-js):
+  @Field.d(1, "string", "optional", "awesome default string")
+  public awesomeField: string;
 
-```js
-const grpc = require('@grpc/grpc-js');
+  @Field.d(2, AwesomeSubMessage)
+  public awesomeSubMessage: AwesomeSubMessage;
 
-const Client = grpc.makeGenericClientConstructor({});
-const client = new Client(serverAddress, grpc.credentials.createInsecure());
+  @Field.d(3, AwesomeEnum, "optional", AwesomeEnum.ONE)
+  public awesomeEnum: AwesomeEnum;
 
-const rpcImpl = (method, requestData, callback) =>
-  client.makeUnaryRequest(method.path, (data) => data, (data) => data, requestData, callback);
+  @OneOf.d("awesomeSubMessage", "awesomeEnum")
+  public which: string;
 
-const greeter = root.lookupService("example.Greeter").create(rpcImpl);
-const reply = await greeter.sayHello({ name: "world" });
-```
+}
 
-See [examples/grpc-service.js](./examples/grpc-service.js) for a complete example.
+// example code
+let message = new AwesomeMessage({ awesomeField: "hello" });
+let buffer  = AwesomeMessage.encode(message).finish();
+let decoded = AwesomeMessage.decode(buffer);
+```
 
-### Extensions
+Supported decorators are:
 
-The following extensions provide descriptor conversion and text-based protobuf formats when reflection metadata is available. Most applications only need the binary APIs above.
+* **Type.d(typeName?: `string`)** &nbsp; *(optional)*<br />
+  annotates a class as a protobuf message type. If `typeName` is not specified, the constructor's runtime function name is used for the reflected type.
 
-#### Descriptors
+* **Field.d&lt;T>(fieldId: `number`, fieldType: `string | Constructor<T>`, fieldRule?: `"optional" | "required" | "repeated"`, defaultValue?: `T`)**<br />
+  annotates a property as a protobuf field with the specified id and protobuf type.
 
-protobuf.js uses a compact JSON-based reflection representation internally that is easy to embed and fast to parse, so schemas can be loaded directly without first decoding binary descriptor blobs or postprocessing their full JSON representation. See [ext/descriptor](./ext/README.md#descriptor) for use cases that need conversion between reflected roots and `protoc` descriptor messages.
+* **MapField.d&lt;T extends { [key: string]: any }>(fieldId: `number`, fieldKeyType: `string`, fieldValueType. `string | Constructor<{}>`)**<br />
+  annotates a property as a protobuf map field with the specified id, protobuf key and value type.
 
-#### ProtoJSON
+* **OneOf.d&lt;T extends string>(...fieldNames: `string[]`)**<br />
+  annotates a property as a protobuf oneof covering the specified fields.
 
-Protocol Buffers support a special [ProtoJSON format](https://protobuf.dev/programming-guides/json/) to share data with systems that do not support the binary wire format, for example when implementing gateways. Spec-compliant ProtoJSON is supported via [ext/protojson](./ext/README.md#protojson).
+Other notes:
 
-#### Text Format
+* Decorated types reside in `protobuf.roots["decorated"]` using a flat structure, so no duplicate names.
+* Enums are copied to a reflected enum with a generic name on decorator evaluation because referenced enum objects have no runtime name the decorator could use.
+* Default values must be specified as arguments to the decorator instead of using a property initializer for proper prototype behavior.
+* Property names on decorated classes must not be renamed on compile time (i.e. by a minifier) because decorators just receive the original field name as a string.
 
-Protocol Buffers [Text Format](https://protobuf.dev/reference/protobuf/textformat-spec/) is a special syntax for representing protobuf data in text form, which can be useful for configurations or tests. Spec-compliant Text Format is supported via [ext/textformat](./ext/README.md#textformat).
+**ProTip!** Not as pretty, but you can [use decorators in plain JavaScript](https://github.com/protobufjs/protobuf.js/blob/master/examples/js-decorators.js) as well.
 
-## Conformance
+Additional documentation
+------------------------
 
-protobuf.js is validated against the official Protocol Buffers conformance suite, achieving complete binary wire-format conformance for **Proto2**, **Proto3** and **Editions**, plus complete **ProtoJSON** and **Text Format** conformance in its default configuration with reflection metadata present.
+#### Protocol Buffers
+* [Google's Developer Guide](https://protobuf.dev/overview/)
 
-<!-- BEGIN CONFORMANCE DATA -->
+#### protobuf.js
+* [API Documentation](https://protobufjs.github.io/protobuf.js)
+* [CHANGELOG](https://github.com/protobufjs/protobuf.js/blob/master/CHANGELOG.md)
+* [Frequently asked questions](https://github.com/protobufjs/protobuf.js/wiki) on our wiki
 
-| Category   |               Total |            Required |         Recommended |
-| ---------- | ------------------: | ------------------: | ------------------: |
-| Binary     | 100.00% (2835/2835) | 100.00% (1958/1958) |   100.00% (877/877) |
-| ↳ Proto2   |   100.00% (707/707) |   100.00% (489/489) |   100.00% (218/218) |
-| ↳ Proto3   |   100.00% (707/707) |   100.00% (486/486) |   100.00% (221/221) |
-| ↳ Editions | 100.00% (1421/1421) |   100.00% (983/983) |   100.00% (438/438) |
-| ProtoJSON  | 100.00% (2796/2796) | 100.00% (2362/2362) |   100.00% (434/434) |
-| TextFormat |   100.00% (909/909) |   100.00% (845/845) |     100.00% (64/64) |
-| Overall    | 100.00% (6540/6540) | 100.00% (5165/5165) | 100.00% (1375/1375) |
+#### Community
+* [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow
 
-<!-- END CONFORMANCE DATA -->
+Performance
+-----------
+The package includes a benchmark that compares protobuf.js performance to native JSON (as far as this is possible) and [Google's JS implementation](https://github.com/google/protobuf/tree/master/js). On an i7-2600K running node 6.9.1 it yields:
 
-[Structured results](https://github.com/protobufjs/protobuf.js/actions/workflows/test.yml?query=branch%3Amaster+event%3Apush) are available as CI artifacts. In case of contradicting claims by your favorite LLM, [see](https://dev.to/dcode/when-the-model-is-the-marketing-device-a-protobuf-short-story-2p7p).
+```
+benchmarking encoding performance ...
+
+protobuf.js (reflect) x 541,707 ops/sec ±1.13% (87 runs sampled)
+protobuf.js (static) x 548,134 ops/sec ±1.38% (89 runs sampled)
+JSON (string) x 318,076 ops/sec ±0.63% (93 runs sampled)
+JSON (buffer) x 179,165 ops/sec ±2.26% (91 runs sampled)
+google-protobuf x 74,406 ops/sec ±0.85% (86 runs sampled)
+
+   protobuf.js (static) was fastest
+  protobuf.js (reflect) was 0.9% ops/sec slower (factor 1.0)
+          JSON (string) was 41.5% ops/sec slower (factor 1.7)
+          JSON (buffer) was 67.6% ops/sec slower (factor 3.1)
+        google-protobuf was 86.4% ops/sec slower (factor 7.3)
+
+benchmarking decoding performance ...
+
+protobuf.js (reflect) x 1,383,981 ops/sec ±0.88% (93 runs sampled)
+protobuf.js (static) x 1,378,925 ops/sec ±0.81% (93 runs sampled)
+JSON (string) x 302,444 ops/sec ±0.81% (93 runs sampled)
+JSON (buffer) x 264,882 ops/sec ±0.81% (93 runs sampled)
+google-protobuf x 179,180 ops/sec ±0.64% (94 runs sampled)
+
+  protobuf.js (reflect) was fastest
+   protobuf.js (static) was 0.3% ops/sec slower (factor 1.0)
+          JSON (string) was 78.1% ops/sec slower (factor 4.6)
+          JSON (buffer) was 80.8% ops/sec slower (factor 5.2)
+        google-protobuf was 87.0% ops/sec slower (factor 7.7)
+
+benchmarking combined performance ...
+
+protobuf.js (reflect) x 275,900 ops/sec ±0.78% (90 runs sampled)
+protobuf.js (static) x 290,096 ops/sec ±0.96% (90 runs sampled)
+JSON (string) x 129,381 ops/sec ±0.77% (90 runs sampled)
+JSON (buffer) x 91,051 ops/sec ±0.94% (90 runs sampled)
+google-protobuf x 42,050 ops/sec ±0.85% (91 runs sampled)
+
+   protobuf.js (static) was fastest
+  protobuf.js (reflect) was 4.7% ops/sec slower (factor 1.0)
+          JSON (string) was 55.3% ops/sec slower (factor 2.2)
+          JSON (buffer) was 68.6% ops/sec slower (factor 3.2)
+        google-protobuf was 85.5% ops/sec slower (factor 6.9)
+```
 
-## Performance
+These results are achieved by
 
-In both reflection and reflection-free modes, protobuf.js builds specialized encoders and decoders on top of hand-tuned reader and writer primitives, making it a strong fit from battery-powered devices to high-traffic servers, or generally for projects and their downstream users adopting protobuf as a faster, smaller alternative to JSON.
+* generating type-specific encoders, decoders, verifiers and converters at runtime
+* configuring the reader/writer interface according to the environment
+* using node-specific functionality where beneficial and, of course
+* avoiding unnecessary operations through splitting up [the toolset](#toolset).
 
-The repository includes a [small benchmark](./bench) over a common message shape, plus Mapbox's vector tile fixture and Buf's perf payload, both unmodified. For each case, it compares protobuf.js encode and decode throughput against JSON encode/decode, Google's protoc-gen-js, and Buf's protoc-gen-es. Results show that protobuf.js is consistently faster than the other Protobuf implementations, up to an order of magnitude on real-world data, and among the libraries tested, it is the only one that is an upgrade over using JSON.
+You can also run [the benchmark](https://github.com/protobufjs/protobuf.js/blob/master/bench/index.js) ...
 
-<!-- BEGIN BENCHMARK DATA -->
+```
+$> npm run bench
+```
 
-![Encode benchmark](./bench/results/encode.svg)
+and [the profiler](https://github.com/protobufjs/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node):
 
-| Case | protobuf.js static | protobuf.js reflect | JSON | protoc-gen-js | protoc-gen-es |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Common | 3.18M ops/s | 3.25M ops/s | 2.07M ops/s | 1.01M ops/s | 395K ops/s |
-| Vector tile | 2.82K ops/s | 2.76K ops/s | 859 ops/s | 680 ops/s | 231 ops/s |
-| Buf perf | 41.4K ops/s | 39.9K ops/s | 6.59K ops/s | 13.5K ops/s | 8.00K ops/s |
+```
+$> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000]
+```
 
-![Decode benchmark](./bench/results/decode.svg)
+Note that as of this writing, the benchmark suite performs significantly slower on node 7.2.0 compared to 6.9.1 because moths.
 
-| Case | protobuf.js static | protobuf.js reflect | JSON | protoc-gen-js | protoc-gen-es |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| Common | 6.11M ops/s | 6.09M ops/s | 1.31M ops/s | 790K ops/s | 710K ops/s |
-| Vector tile | 2.45K ops/s | 2.78K ops/s | 1.04K ops/s | 858 ops/s | 392 ops/s |
-| Buf perf | 72.5K ops/s | 66.4K ops/s | 19.0K ops/s | 21.1K ops/s | 14.2K ops/s |
+Compatibility
+-------------
 
-<!-- END BENCHMARK DATA -->
+* Works in all modern and not-so-modern browsers except IE8.
+* Because the internals of this package do not rely on `google/protobuf/descriptor.proto`, options are parsed and presented literally.
+* If typed arrays are not supported by the environment, plain arrays will be used instead.
+* Support for pre-ES5 environments (except IE8) can be achieved by [using a polyfill](https://github.com/protobufjs/protobuf.js/blob/master/lib/polyfill.js).
+* Support for [Content Security Policy](https://w3c.github.io/webappsec-csp/)-restricted environments (like Chrome extensions without unsafe-eval) can be achieved by generating and using static code instead.
+* If a proper way to work with 64 bit values (uint64, int64 etc.) is required, just install [long.js](https://github.com/dcodeIO/long.js) alongside this library. All 64 bit numbers will then be returned as a `Long` instance instead of a possibly unsafe JavaScript number ([see](https://github.com/dcodeIO/long.js)).
+* For descriptor.proto interoperability, see [ext/descriptor](https://github.com/protobufjs/protobuf.js/tree/master/ext/descriptor)
 
-[Structured results](./bench/results/latest.json) of this run are available as committed artifacts.
+Building
+--------
 
-To run the benchmark yourself on your own hardware:
+To build the library or its components yourself, clone it from GitHub and install the development dependencies:
 
-```sh
-npm --prefix bench install
-npm run bench
+```
+$> git clone https://github.com/protobufjs/protobuf.js.git
+$> cd protobuf.js
+$> npm install
 ```
 
-## Compatibility
+Building the respective development and production versions with their respective source maps to `dist/`:
 
-Supported runtimes are browsers, Node.js v12+, Deno and Bun. When using the CLI with Bun, Node.js must also be installed.
+```
+$> npm run build
+```
 
-## Security
+Building the documentation to `docs/`:
 
-Security-impacting reports are handled through coordinated GitHub Security Advisories where appropriate. See [SECURITY.md](./SECURITY.md) for supported release lines and reporting instructions.
+```
+$> npm run docs
+```
 
-## Development
+Building the TypeScript definition to `index.d.ts`:
 
-```sh
-git clone https://github.com/protobufjs/protobuf.js
-cd protobuf.js
-npm install
-npm --prefix cli install
+```
+$> npm run build:types
 ```
 
-Running the tests:
+### Browserify integration
 
-```sh
-npm test
-```
+By default, protobuf.js integrates into any browserify build-process without requiring any optional modules. Hence:
 
-Building the development and production versions with their respective source maps to `dist/`:
+* If int64 support is required, explicitly require the `long` module somewhere in your project as it will be excluded otherwise. This assumes that a global `require` function is present that protobuf.js can call to obtain the long module.
 
-```sh
-npm run build
-```
+  If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically:
 
-## Additional documentation
+  ```js
+  var Long = ...;
 
-* [API Documentation](https://protobufjs.github.io/protobuf.js)
-* [Changelog](./CHANGELOG.md)
-* [Protocol Buffers Documentation](https://protobuf.dev/)
+  protobuf.util.Long = Long;
+  protobuf.configure();
+  ```
+
+* If you have any special requirements, there is [the bundler](https://github.com/protobufjs/protobuf.js/blob/master/scripts/bundle.js) for reference.
+
+**License:** [BSD 3-Clause License](https://opensource.org/licenses/BSD-3-Clause)