@openclaw/diagnostics-otel 2026.6.8 → 2026.6.9-beta.1

package/node_modules/protobufjs/README.md

@@ -9,426 +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 standalone JavaScript implementation of Protocol Buffers for Node.js and the browser. It works with `.proto` files out of the box, is optimized for fast binary I/O, and supports runtime reflection as well as reflection-free static 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!
 
-## About
+Contents
+--------
 
-protobuf.js has grown from a personal project into a widely used JavaScript infrastructure library for Protocol Buffers. It is independently maintained, with participation from the upstream Protocol Buffers ecosystem, and is intentionally not tied to any specific vendor platform, commercial service, or schema registry.
+* [Installation](#installation)<br />
+  How to include protobuf.js in your project.
 
-If protobuf.js is important to your project or organization, especially if you depend on it commercially, [consider supporting](https://github.com/sponsors/dcodeIO) its ongoing maintenance.
+* [Usage](#usage)<br />
+  A brief introduction to using the toolset.
 
-## Getting started
+  * [Valid Message](#valid-message)
+  * [Toolset](#toolset)<br />
 
-### Install
+* [Examples](#examples)<br />
+  A few examples to get you started.
 
-```sh
-npm install protobufjs
-```
+  * [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.
 
-The [command line utility](./cli/#readme) for generating reflection bundles, static code and TypeScript declarations is published as an add-on package:
+* [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 --save-dev protobufjs-cli
+npm install protobufjs --save
 ```
 
-The CLI is a small but capable standalone protobuf.js toolchain. It does not require `protoc`, but also provides `protoc-gen-pbjs` for standard `protoc` plugin workflows.
+```js
+// Static code + Reflection + .proto parser
+var protobuf = require("protobufjs");
 
-### Choose a runtime
+// Static code + Reflection
+var protobuf = require("protobufjs/light");
 
-Pick the smallest runtime variant that supports how your application loads schemas and whether it needs reflection at runtime.
+// Static code only
+var protobuf = require("protobufjs/minimal");
+```
 
-| 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
+The optional [command line utility](./cli/) to generate static code and reflection bundles lives in the `protobufjs-cli` package and can be installed separately:
 
-The full build includes the light build, and the light build includes the minimal runtime.
+```sh
+npm install protobufjs-cli --save-dev
+```
 
-### Browser builds
+### Browsers
 
-Pick the distribution matching your runtime variant and pin an exact version:
+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:
 
 ```html
-<!-- Full -->
-<script src="https://cdn.jsdelivr.net/npm/protobufjs@8.X.X/dist/protobuf.min.js"></script>
-<!-- Light -->
-<script src="https://cdn.jsdelivr.net/npm/protobufjs@8.X.X/dist/light/protobuf.min.js"></script>
-<!-- Minimal -->
-<script src="https://cdn.jsdelivr.net/npm/protobufjs@8.X.X/dist/minimal/protobuf.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/protobufjs@7.X.X/dist/protobuf.min.js"></script>
 ```
 
-Browser builds support CommonJS and AMD loaders and export globally as `window.protobuf`.
+| 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/>
 
-## Usage
+All variants support CommonJS and AMD loaders and export globally as `window.protobuf`.
 
-The examples below use this schema:
+Usage
+-----
 
-```proto
-syntax = "proto3";
+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):
+
+### Valid message
+
+> 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.
+
+There are two possible types of valid messages and the encoder is able to work with both of these for convenience:
+
+* **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.
+
+In a nutshell, the wire format writer understands the following types:
+
+| 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
+
+* 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.
+
+### 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:
+
+<p align="center"><img alt="Toolset Diagram" src="https://protobufjs.github.io/protobuf.js/toolset.svg" /></p>
+
+> 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;
+    string awesome_field = 1; // becomes awesomeField
 }
 ```
 
-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.
+```js
+protobuf.load("awesome.proto", function(err, root) {
+    if (err)
+        throw err;
 
-### Load a schema
+    // Obtain a message type
+    var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
 
-```ts
-const protobuf = require("protobufjs");
+    // Exemplary payload
+    var payload = { awesomeField: "AwesomeString" };
 
-const root = await protobuf.load("awesome.proto");
-const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
-```
+    // Verify the payload if necessary (i.e. when possibly incomplete or invalid)
+    var errMsg = AwesomeMessage.verify(payload);
+    if (errMsg)
+        throw Error(errMsg);
 
-Optionally use `load()` with a callback, or `loadSync()` for synchronous loading on Node.js.
+    // Create a new message
+    var message = AwesomeMessage.create(payload); // or use .fromObject if conversion is necessary
 
-### Encode and decode
+    // Encode a message to an Uint8Array (browser) or Buffer (node)
+    var buffer = AwesomeMessage.encode(message).finish();
+    // ... do something with buffer
 
-```ts
-const payload = { awesomeField: "hello" };
+    // Decode an Uint8Array (browser) or Buffer (node) to a message
+    var message = AwesomeMessage.decode(buffer);
+    // ... do something with message
 
-// Optionally verify if the payload is of uncertain shape
-const err = AwesomeMessage.verify(payload);
-if (err) throw Error(err);
+    // If the application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited.
 
-// Optionally create a message instance from already valid data
-const message = AwesomeMessage.create(payload);
+    // Maybe convert the message back to a plain object
+    var object = AwesomeMessage.toObject(message, {
+        longs: String,
+        enums: String,
+        bytes: String,
+        // see ConversionOptions
+    });
+});
+```
 
-const encoded = AwesomeMessage.encode(message).finish();
-const decoded = AwesomeMessage.decode(encoded);
+Additionally, promise syntax can be used by omitting the callback, if preferred:
+
+```js
+protobuf.load("awesome.proto")
+    .then(function(root) {
+       ...
+    });
+```
+
+### 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
+            }
+          }
+        }
+      }
+    }
+  }
+}
 ```
 
-`encode` expects a message instance or equivalent plain object and does not verify input implicitly. Use `verify` for plain objects whose shape is not guaranteed, `create` to create a message instance from already valid data when useful, and `fromObject` when conversion from broader JavaScript objects is needed.
+JSON descriptors closely resemble the internal reflection structure:
 
-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/`Long` keys.
+| 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
 
-Install [`long`](https://github.com/dcodeIO/long.js) with protobuf.js when exact 64-bit integer support is required.
+* **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)
 
-### Convert plain objects
+Exclusively using JSON descriptors instead of .proto files enables the use of just the light library (the parser isn't required in this case).
 
-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.
+A JSON descriptor can either be loaded the usual way:
 
-```ts
-const message = AwesomeMessage.fromObject({ awesomeField: 42 });
-const object = AwesomeMessage.toObject(message, {
-  longs: String,
-  enums: String,
-  bytes: String
+```js
+protobuf.load("awesome.json", function(err, root) {
+    if (err) throw err;
+
+    // Continue at "Obtain a message type" above
 });
 ```
 
-Common `ConversionOptions` are:
+Or it can be loaded inline:
 
-| 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
+var jsonDescriptor = require("./awesome.json"); // exemplary for node
 
-## Message API
+var root = protobuf.Root.fromJSON(jsonDescriptor);
 
-Message types expose focused methods for validation, conversion, and binary I/O.
+// Continue at "Obtain a message type" above
+```
 
-* **encode**(message: `Message | object`, writer?: `Writer`): `Writer`  
-  Encodes a message or equivalent plain object. Call `.finish()` on the returned writer to obtain a buffer.
+### Using reflection only
 
-* **encodeDelimited**(message: `Message | object`, writer?: `Writer`): `Writer`  
-  Encodes a length-delimited message.
+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:
 
-* **decode**(reader: `Reader | Uint8Array`): `Message`  
-  Decodes a message from protobuf binary data.
+```js
+...
+var Root  = protobuf.Root,
+    Type  = protobuf.Type,
+    Field = protobuf.Field;
 
-* **decodeDelimited**(reader: `Reader | Uint8Array`): `Message`  
-  Decodes a length-delimited message.
+var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string"));
 
-* **create**(properties?: `object`): `Message`  
-  Creates a message instance from already valid data.
+var root = new Root().define("awesomepackage").add(AwesomeMessage);
 
-* **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 "Create a new message" above
+...
+```
 
-* **fromObject**(object: `object`): `Message`  
-  Converts broader JavaScript input into a message instance.
+Detailed information on the reflection structure is available within the [API documentation](#additional-documentation).
 
-* **toObject**(message: `Message`, options?: `ConversionOptions`): `object`  
-  Converts a message instance to a configurable plain JavaScript object.
+### Using custom classes
 
-* **message#toJSON**(): `object`  
-  Converts a message instance to JSON-compatible output using default conversion options.
+Message classes can also be extended with custom functionality and it is also possible to register a custom constructor with a reflected message type:
 
-Length-delimited methods read and write a varint byte length before the message, which is useful for streams and framed protocols.
+```js
+...
 
-If required fields are missing while decoding proto2 data, `decode` throws `protobuf.util.ProtocolError` with the partially decoded message available as `err.instance`.
+// Define a custom constructor
+function AwesomeMessage(properties) {
+    // custom initialization code
+    ...
+}
 
-## Code generation
+// Register the custom constructor with its reflected type (*)
+root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
 
-Choose the integration style that fits your workflow and use [`protobufjs-cli`](./cli/#readme) to generate reflection bundles, static JavaScript code, and matching TypeScript declarations, either standalone with `pbjs` or through its `protoc-gen-pbjs` plugin for `protoc`.
+// Define custom functionality
+AwesomeMessage.customStaticMethod = function() { ... };
+AwesomeMessage.prototype.customInstanceMethod = function() { ... };
 
-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.
+// Continue at "Create a new message" above
+```
 
-| 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` |
+(*) Besides referencing its reflected type through `AwesomeMessage.$type` and `AwesomeMesage#$type`, the respective custom class is automatically populated with:
 
-Module targets support `--wrap default` for CommonJS and AMD, plus `esm`, `commonjs`, `amd`, and `closure`; `--wrap` can also load a custom wrapper module.
+* `AwesomeMessage.create`
+* `AwesomeMessage.encode` and `AwesomeMessage.encodeDelimited`
+* `AwesomeMessage.decode` and `AwesomeMessage.decodeDelimited`
+* `AwesomeMessage.verify`
+* `AwesomeMessage.fromObject`, `AwesomeMessage.toObject` and `AwesomeMessage#toJSON`
 
-### Static modules
+Afterwards, decoded messages of this type are `instanceof AwesomeMessage`.
 
-Static modules emit dedicated JavaScript for your schema, so they only need `protobufjs/minimal.js` at runtime.
+Alternatively, it is also possible to reuse and extend the internal constructor if custom initialization code is not required:
 
-```sh
-npx pbjs -t static-module -w esm -o awesome.js --dts awesome.proto
-```
+```js
+...
 
-```ts
-import { awesomepackage } from "./awesome.js";
+// Reuse the internal constructor
+var AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage").ctor;
 
-const message = awesomepackage.AwesomeMessage.create({ awesomeField: "hello" });
+// Define custom functionality
+AwesomeMessage.customStaticMethod = function() { ... };
+AwesomeMessage.prototype.customInstanceMethod = function() { ... };
+
+// Continue at "Create a new message" above
 ```
 
-### Reflection bundles
+### Using services
 
-Bundling schemas avoids reparsing `.proto` files at runtime and can reduce browser requests when schemas would otherwise be loaded separately. While reflection requires at least `protobufjs/light.js`, large schemas often produce smaller bundles than equivalent static modules because most code is shared via reflection.
+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:
 
-```sh
-npx pbjs -t json -o awesome.json awesome1.proto awesome2.proto ...
+```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
-const bundle = require("./awesome.json");
+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
+  )
+}
+```
+
+Example:
+
+```protobuf
+// greeter.proto
+syntax = "proto3";
 
-const root = protobuf.Root.fromJSON(bundle);
-const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
+service Greeter {
+    rpc SayHello (HelloRequest) returns (HelloReply) {}
+}
+
+message HelloRequest {
+    string name = 1;
+}
+
+message HelloReply {
+    string message = 1;
+}
 ```
 
-```sh
-npx pbjs -t json-module -w esm -o awesome.js --dts awesome.proto
+```js
+...
+var Greeter = root.lookup("Greeter");
+var greeter = Greeter.create(/* see above */ rpcImpl, /* request delimited? */ false, /* response delimited? */ false);
+
+greeter.sayHello({ name: 'you' }, function(err, response) {
+    console.log('Greeting:', response.message);
+});
 ```
 
-```ts
-import { awesomepackage } from "./awesome.js";
+Services also support promises:
 
-const AwesomeMessage = awesomepackage.AwesomeMessage;
+```js
+greeter.sayHello({ name: 'you' })
+    .then(function(response) {
+        console.log('Greeting:', response.message);
+    });
 ```
 
-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.
+There is also an [example for streaming RPC](https://github.com/protobufjs/protobuf.js/blob/master/examples/streaming-rpc.js).
 
-### TypeScript integration
+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.
 
-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.
+### Usage with TypeScript
 
-For example, given the oneof:
+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.
 
-```proto
-message Profile {
-  oneof contact {
-    string email = 1;
-    string phone = 2;
-  }
-}
-```
+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.
 
-Generated declarations narrow both the `contact` oneof and the concrete values:
+#### 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 profile = Profile.create({
-  contact: "email",
-  email: "hello@example.com"
-});
+import { load } from "protobufjs"; // respectively "./node_modules/protobufjs"
 
-if (profile.contact === "email") {
-  profile.email; // string
-}
+load("awesome.proto", function(err, root) {
+  if (err)
+    throw err;
 
-const decoded = Profile.decode(bytes);
-if (decoded.contact === "phone") {
-  decoded.phone; // string
-}
-```
+  // example code
+  const AwesomeMessage = root.lookupType("awesomepackage.AwesomeMessage");
 
-Plain objects can use the same narrowed shape through a collision-free scoped type:
+  let message = AwesomeMessage.create({ awesomeField: "hello" });
+  console.log(`message = ${JSON.stringify(message)}`);
 
-```ts
-const object: Profile.$Shape = {
-  contact: "email",
-  email: "hello@example.com"
-};
-```
+  let buffer = AwesomeMessage.encode(message).finish();
+  console.log(`buffer = ${Array.prototype.toString.call(buffer)}`);
 
-## Advanced usage
+  let decoded = AwesomeMessage.decode(buffer);
+  console.log(`decoded = ${JSON.stringify(decoded)}`);
+});
+```
 
-### Programmatic schemas
+#### Using generated static code
 
-The full and light builds can construct schemas directly through reflection:
+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
-const AwesomeMessage = new protobuf.Type("AwesomeMessage")
-  .add(new protobuf.Field("awesomeField", 1, "string"));
+import { AwesomeMessage } from "./bundle.js";
 
-const root = new protobuf.Root()
-  .define("awesomepackage")
-  .add(AwesomeMessage);
+// example code
+let message = AwesomeMessage.create({ awesomeField: "hello" });
+let buffer  = AwesomeMessage.encode(message).finish();
+let decoded = AwesomeMessage.decode(buffer);
 ```
 
-### Custom message classes
+#### Using decorators
+
+The library also includes an early implementation of [decorators](https://www.typescriptlang.org/docs/handbook/decorators.html).
 
-A reflected type can use a custom class as its runtime constructor:
+**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`.
 
 ```ts
-class AwesomeMessage extends protobuf.Message<AwesomeMessage> {
-  awesomeField = "";
+import { Message, Type, Field, OneOf } from "protobufjs/light"; // respectively "./node_modules/protobufjs/light.js"
 
-  constructor(properties?: protobuf.Properties<AwesomeMessage>) {
-    super(properties);
-    // ...
-  }
+export class AwesomeSubMessage extends Message<AwesomeSubMessage> {
+
+  @Field.d(1, "string")
+  public awesomeString: string;
 
-  customInstanceMethod() {
-    return this.awesomeField.toLowerCase();
-  }
 }
 
-root.lookupType("awesomepackage.AwesomeMessage").ctor = AwesomeMessage;
+export enum AwesomeEnum {
+  ONE = 1,
+  TWO = 2
+}
 
-const decoded = AwesomeMessage.decode(bytes);
-decoded.customInstanceMethod(); // string
-```
+@Type.d("SuperAwesomeMessage")
+export class AwesomeMessage extends Message<AwesomeMessage> {
 
-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.
+  @Field.d(1, "string", "optional", "awesome default string")
+  public awesomeField: string;
 
-### Services
+  @Field.d(2, AwesomeSubMessage)
+  public awesomeSubMessage: AwesomeSubMessage;
 
-protobuf.js supports service clients built from reflected service definitions. The service API is transport-agnostic: provide an `rpcImpl` function to connect it to HTTP, WebSocket, gRPC, or another transport. See [examples/streaming-rpc.js](./examples/streaming-rpc.js) for details.
+  @Field.d(3, AwesomeEnum, "optional", AwesomeEnum.ONE)
+  public awesomeEnum: AwesomeEnum;
 
-### Descriptors
+  @OneOf.d("awesomeSubMessage", "awesomeEnum")
+  public which: string;
 
-For `google/protobuf/descriptor.proto` interoperability, see [ext/descriptor](./ext/README.md#descriptor). Note that because protobuf.js does not use `descriptor.proto` internally, options are parsed and presented literally.
+}
 
-### Text format
+// example code
+let message = new AwesomeMessage({ awesomeField: "hello" });
+let buffer  = AwesomeMessage.encode(message).finish();
+let decoded = AwesomeMessage.decode(buffer);
+```
 
-Protocol Buffers Text Format is supported via [ext/textformat](./ext/README.md#textformat) and exercised by the conformance suite.
+Supported decorators are:
 
-### Content Security Policy
+* **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.
 
-In [CSP](https://w3c.github.io/webappsec-csp/)-restricted environments that disallow unsafe-eval, use generated static code instead of runtime code generation.
+* **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.
 
-## Conformance
+* **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.
 
-protobuf.js targets complete binary wire-format conformance for **Proto2**, **Proto3** and **Editions**. CI runs the official Protocol Buffers conformance suite, with logs [uploaded as artifacts](https://github.com/protobufjs/protobuf.js/actions/workflows/test.yml?query=branch%3Amaster+event%3Apush).
+* **OneOf.d&lt;T extends string>(...fieldNames: `string[]`)**<br />
+  annotates a property as a protobuf oneof covering the specified fields.
 
-Wire format by syntax:
+Other notes:
 
-| Syntax   |               Total |          Required |       Recommended |
-| -------- | ------------------: | ----------------: | ----------------: |
-| Proto2   |   100.00% (694/694) | 100.00% (485/485) | 100.00% (209/209) |
-| Proto3   |   100.00% (689/689) | 100.00% (482/482) | 100.00% (207/207) |
-| Editions | 100.00% (1176/1176) | 100.00% (926/926) | 100.00% (250/250) |
+* 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.
 
-## Performance
+**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.
 
-In both reflection and static modes, protobuf.js builds specialized encoders and decoders instead of interpreting descriptors at runtime.
+Additional documentation
+------------------------
 
-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.
+#### Protocol Buffers
+* [Google's Developer Guide](https://protobuf.dev/overview/)
 
-<details>
-<summary>Benchmark run on AMD Ryzen 9 9950X3D with Node.js 24.15.0</summary>
+#### 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
 
-```
-benchmarking encode performance ...
+#### Community
+* [Questions and answers](http://stackoverflow.com/search?tab=newest&q=protobuf.js) on StackOverflow
 
-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)
+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:
 
-    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 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)
+```
 
-benchmarking decode performance ...
+These results are achieved by
 
-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)
+* 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).
 
-     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)
+You can also run [the benchmark](https://github.com/protobufjs/protobuf.js/blob/master/bench/index.js) ...
 
-benchmarking round-trip performance ...
+```
+$> npm run bench
+```
 
-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)
+and [the profiler](https://github.com/protobufjs/protobuf.js/blob/master/bench/prof.js) yourself (the latter requires a recent version of node):
 
-    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)
 ```
-</details>
+$> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000]
+```
 
-Run it locally with:
+Note that as of this writing, the benchmark suite performs significantly slower on node 7.2.0 compared to 6.9.1 because moths.
 
-```sh
-npm --prefix bench install
-npm run bench
-```
+Compatibility
+-------------
 
-## Compatibility
+* 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)
 
-Supported runtimes are browsers, Node.js v12+, Deno and Bun. When using the CLI with Bun, Node.js must also be installed.
+Building
+--------
 
-## Security
+To build the library or its components yourself, clone it from GitHub and install the development dependencies:
 
-Security-impacting reports are handled through coordinated GitHub Security Advisories where appropriate. See [SECURITY.md](./SECURITY.md) for supported release lines and reporting instructions.
+```
+$> git clone https://github.com/protobufjs/protobuf.js.git
+$> cd protobuf.js
+$> npm install
+```
 
-## Development
+Building the respective development and production versions with their respective source maps to `dist/`:
 
-```sh
-git clone https://github.com/protobufjs/protobuf.js
-cd protobuf.js
-npm install
-npm --prefix cli install
+```
+$> npm run build
 ```
 
-Running the tests:
+Building the documentation to `docs/`:
 
-```sh
-npm test
+```
+$> npm run docs
 ```
 
-Building the development and production versions with their respective source maps to `dist/`:
+Building the TypeScript definition to `index.d.ts`:
 
-```sh
-npm run build
+```
+$> npm run build:types
 ```
 
-## Additional documentation
+### Browserify integration
 
-* [API Documentation](https://protobufjs.github.io/protobuf.js)
-* [Changelog](./CHANGELOG.md)
-* [Protocol Buffers Documentation](https://protobuf.dev/)
+By default, protobuf.js integrates into any browserify build-process without requiring any optional modules. Hence:
+
+* 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.
+
+  If there is no global `require` function present after bundling, it's also possible to assign the long module programmatically:
+
+  ```js
+  var Long = ...;
+
+  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)