@bufbuild/protobuf 2.0.0-alpha.1 → 2.0.0-alpha.3

package/dist/esm/proto-int64.js

@@ -11,8 +11,11 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-import { assert } from "./reflect/assert.js";
 import { int64FromString, int64ToString, uInt64ToString, } from "./wire/varint.js";
+/**
+ * Int64Support for the current environment.
+ */
+export const protoInt64 = /*@__PURE__*/ makeInt64Support();
 function makeInt64Support() {
     const dv = new DataView(new ArrayBuffer(8));
     // note that Safari 14 implements BigInt, but not the DataView methods
@@ -32,14 +35,14 @@ function makeInt64Support() {
             parse(value) {
                 const bi = typeof value == "bigint" ? value : BigInt(value);
                 if (bi > MAX || bi < MIN) {
-                    throw new Error(`int64 invalid: ${value}`);
+                    throw new Error(`invalid int64: ${value}`);
                 }
                 return bi;
             },
             uParse(value) {
                 const bi = typeof value == "bigint" ? value : BigInt(value);
                 if (bi > UMAX || bi < UMIN) {
-                    throw new Error(`uint64 invalid: ${value}`);
+                    throw new Error(`invalid uint64: ${value}`);
                 }
                 return bi;
             },
@@ -69,8 +72,6 @@ function makeInt64Support() {
             },
         };
     }
-    const assertInt64String = (value) => assert(/^-?[0-9]+$/.test(value), `int64 invalid: ${value}`);
-    const assertUInt64String = (value) => assert(/^[0-9]+$/.test(value), `uint64 invalid: ${value}`);
     return {
         zero: "0",
         supported: false,
@@ -110,4 +111,13 @@ function makeInt64Support() {
         },
     };
 }
-export const protoInt64 = makeInt64Support();
+function assertInt64String(value) {
+    if (!/^-?[0-9]+$/.test(value)) {
+        throw new Error("invalid int64: " + value);
+    }
+}
+function assertUInt64String(value) {
+    if (!/^[0-9]+$/.test(value)) {
+        throw new Error("invalid uint64: " + value);
+    }
+}

package/dist/esm/reflect/error.d.ts

@@ -1,4 +1,4 @@
-import type { DescField, DescOneof } from "../desc-types.js";
+import type { DescField, DescOneof } from "../descriptors.js";
 declare const errorNames: string[];
 export declare class FieldError extends Error {
     readonly name: (typeof errorNames)[number];

package/dist/esm/reflect/guard.d.ts

@@ -1,7 +1,7 @@
 import type { Message } from "../types.js";
 import type { ScalarValue } from "./scalar.js";
 import type { ReflectList, ReflectMap, ReflectMessage } from "./reflect-types.js";
-import type { DescField, DescMessage } from "../desc-types.js";
+import type { DescField, DescMessage } from "../descriptors.js";
 export declare function isObject(arg: unknown): arg is Record<string, unknown>;
 export declare function isOneofADT(arg: unknown): arg is OneofADT;
 export type OneofADT = {

package/dist/esm/reflect/index.d.ts

@@ -3,6 +3,5 @@ export * from "./names.js";
 export * from "./nested-types.js";
 export * from "./reflect.js";
 export * from "./reflect-types.js";
-export * from "./registry.js";
 export * from "./scalar.js";
 export { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";

package/dist/esm/reflect/index.js

@@ -16,6 +16,5 @@ export * from "./names.js";
 export * from "./nested-types.js";
 export * from "./reflect.js";
 export * from "./reflect-types.js";
-export * from "./registry.js";
 export * from "./scalar.js";
 export { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";

package/dist/esm/reflect/names.d.ts

@@ -1,15 +1,3 @@
-import type { DescEnumValue, DescField } from "../desc-types.js";
-import type { DescMethod, DescOneof } from "../desc-types.js";
-/**
- * Returns the name of a protobuf element in generated code.
- *
- * Field names - including oneofs - are converted to lowerCamelCase. For methods,
- * the first character is made lowercase. All names are escaped to be safe object
- * property names.
- *
- * This function does not provide names for messages, enumerations, and services.
- */
-export declare function localName(desc: DescEnumValue | DescOneof | DescField | DescMethod): string;
 /**
  * Converts snake_case to protoCamelCase according to the convention
  * used by protoc to convert a field name to a JSON name.
@@ -18,6 +6,6 @@ export declare function protoCamelCase(snakeCase: string): string;
 /**
  * Escapes names that are reserved for ECMAScript built-in object properties.
  *
- * Also see safeIdentifier() from @bufbuild/protoplugin/ecmascript.
+ * Also see safeIdentifier() from @bufbuild/protoplugin.
  */
 export declare function safeObjectProperty(name: string): string;

package/dist/esm/reflect/names.js

@@ -11,43 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-/**
- * Returns the name of a protobuf element in generated code.
- *
- * Field names - including oneofs - are converted to lowerCamelCase. For methods,
- * the first character is made lowercase. All names are escaped to be safe object
- * property names.
- *
- * This function does not provide names for messages, enumerations, and services.
- */
-export function localName(desc) {
-    const name = desc.name;
-    switch (desc.kind) {
-        // @ts-expect-error TS7029
-        case "field":
-            if (desc.oneof !== undefined) {
-                // oneof member names are not properties, but values of the `case` property.
-                return protoCamelCase(name);
-            }
-        // eslint-disable-next-line no-fallthrough
-        case "oneof":
-            return safeObjectProperty(protoCamelCase(name));
-        case "enum_value": {
-            let name = desc.name;
-            const sharedPrefix = desc.parent.sharedPrefix;
-            if (sharedPrefix !== undefined) {
-                name = name.substring(sharedPrefix.length);
-            }
-            return safeObjectProperty(name);
-        }
-        case "rpc": {
-            if (name.length == 0) {
-                return name;
-            }
-            return safeObjectProperty(name[0].toLowerCase() + name.substring(1));
-        }
-    }
-}
 /**
  * Converts snake_case to protoCamelCase according to the convention
  * used by protoc to convert a field name to a JSON name.
@@ -99,7 +62,7 @@ const reservedObjectProperties = new Set([
 /**
  * Escapes names that are reserved for ECMAScript built-in object properties.
  *
- * Also see safeIdentifier() from @bufbuild/protoplugin/ecmascript.
+ * Also see safeIdentifier() from @bufbuild/protoplugin.
  */
 export function safeObjectProperty(name) {
     return reservedObjectProperties.has(name) ? name + "$" : name;

package/dist/esm/reflect/nested-types.d.ts

@@ -1,2 +1,12 @@
-import type { DescEnum, DescExtension, DescFile, DescMessage, DescService } from "../desc-types.js";
+import type { AnyDesc, DescEnum, DescExtension, DescFile, DescMessage, DescService } from "../descriptors.js";
+/**
+ * Iterate over all types - enumerations, extensions, services, messages -
+ * and enumerations, extensions and messages nested in messages.
+ */
 export declare function nestedTypes(desc: DescFile | DescMessage): Iterable<DescMessage | DescEnum | DescExtension | DescService>;
+/**
+ * Returns the ancestors of a given Protobuf element, up to the file.
+ */
+export declare function parentTypes(desc: AnyDesc): Parent[];
+type Parent = DescFile | DescEnum | DescMessage | DescService;
+export {};

package/dist/esm/reflect/nested-types.js

@@ -11,6 +11,10 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+/**
+ * Iterate over all types - enumerations, extensions, services, messages -
+ * and enumerations, extensions and messages nested in messages.
+ */
 export function* nestedTypes(desc) {
     switch (desc.kind) {
         case "file":
@@ -32,3 +36,31 @@ export function* nestedTypes(desc) {
             break;
     }
 }
+/**
+ * Returns the ancestors of a given Protobuf element, up to the file.
+ */
+export function parentTypes(desc) {
+    const parents = [];
+    while (desc.kind !== "file") {
+        const p = parent(desc);
+        desc = p;
+        parents.push(p);
+    }
+    return parents;
+}
+function parent(desc) {
+    var _a;
+    switch (desc.kind) {
+        case "enum_value":
+        case "field":
+        case "oneof":
+        case "rpc":
+            return desc.parent;
+        case "service":
+            return desc.file;
+        case "extension":
+        case "enum":
+        case "message":
+            return (_a = desc.parent) !== null && _a !== void 0 ? _a : desc.file;
+    }
+}

package/dist/esm/reflect/reflect-check.d.ts

@@ -1,9 +1,18 @@
-import type { DescField } from "../desc-types.js";
+import { type DescField } from "../descriptors.js";
 import { FieldError } from "./error.js";
+/**
+ * Check whether the given field value is valid for the reflect API.
+ */
 export declare function checkField(field: DescField, value: unknown): FieldError | undefined;
+/**
+ * Check whether the given list item is valid for the reflect API.
+ */
 export declare function checkListItem(field: DescField & {
     fieldKind: "list";
 }, index: number, value: unknown): FieldError | undefined;
+/**
+ * Check whether the given map key and value are valid for the reflect API.
+ */
 export declare function checkMapEntry(field: DescField & {
     fieldKind: "map";
 }, key: unknown, value: unknown): FieldError | undefined;

package/dist/esm/reflect/reflect-check.js

@@ -11,11 +11,16 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-import { ScalarType, scalarTypeDescription } from "./scalar.js";
-import { checkScalarValue } from "./scalar.js";
+import { ScalarType, } from "../descriptors.js";
 import { isMessage } from "../is-message.js";
 import { FieldError } from "./error.js";
 import { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";
+import { FLOAT32_MAX, FLOAT32_MIN, INT32_MAX, INT32_MIN, UINT32_MAX, } from "../wire/binary-encoding.js";
+import { getTextEncoding } from "../wire/text-encoding.js";
+import { protoInt64 } from "../proto-int64.js";
+/**
+ * Check whether the given field value is valid for the reflect API.
+ */
 export function checkField(field, value) {
     const check = field.fieldKind == "list"
         ? isReflectList(value, field)
@@ -39,6 +44,9 @@ export function checkField(field, value) {
     }
     return new FieldError(field, reason);
 }
+/**
+ * Check whether the given list item is valid for the reflect API.
+ */
 export function checkListItem(field, index, value) {
     const check = checkSingular(field, value);
     if (check !== true) {
@@ -46,6 +54,9 @@ export function checkListItem(field, index, value) {
     }
     return undefined;
 }
+/**
+ * Check whether the given map key and value are valid for the reflect API.
+ */
 export function checkMapEntry(field, key, value) {
     const checkKey = checkScalarValue(key, field.mapKey);
     if (checkKey !== true) {
@@ -69,6 +80,84 @@ function checkSingular(field, value) {
     }
     return isReflectMessage(value, field.message);
 }
+function checkScalarValue(value, scalar) {
+    switch (scalar) {
+        case ScalarType.DOUBLE:
+            return typeof value == "number";
+        case ScalarType.FLOAT:
+            if (typeof value != "number") {
+                return false;
+            }
+            if (Number.isNaN(value) || !Number.isFinite(value)) {
+                return true;
+            }
+            if (value > FLOAT32_MAX || value < FLOAT32_MIN) {
+                return `${value.toFixed()} out of range`;
+            }
+            return true;
+        case ScalarType.INT32:
+        case ScalarType.SFIXED32:
+        case ScalarType.SINT32:
+            // signed
+            if (typeof value !== "number" || !Number.isInteger(value)) {
+                return false;
+            }
+            if (value > INT32_MAX || value < INT32_MIN) {
+                return `${value.toFixed()} out of range`;
+            }
+            return true;
+        case ScalarType.FIXED32:
+        case ScalarType.UINT32:
+            // unsigned
+            if (typeof value !== "number" || !Number.isInteger(value)) {
+                return false;
+            }
+            if (value > UINT32_MAX || value < 0) {
+                return `${value.toFixed()} out of range`;
+            }
+            return true;
+        case ScalarType.BOOL:
+            return typeof value == "boolean";
+        case ScalarType.STRING:
+            if (typeof value != "string") {
+                return false;
+            }
+            return getTextEncoding().checkUtf8(value) || "invalid UTF8";
+        case ScalarType.BYTES:
+            return value instanceof Uint8Array;
+        case ScalarType.INT64:
+        case ScalarType.SFIXED64:
+        case ScalarType.SINT64:
+            // signed
+            if (typeof value != "string" &&
+                typeof value !== "bigint" &&
+                typeof value !== "number") {
+                return false;
+            }
+            try {
+                protoInt64.parse(value);
+            }
+            catch (e) {
+                return `${value} out of range`;
+            }
+            return true;
+        case ScalarType.FIXED64:
+        case ScalarType.UINT64:
+            // unsigned
+            if (typeof value != "string" &&
+                typeof value !== "bigint" &&
+                typeof value !== "number") {
+                return false;
+            }
+            try {
+                protoInt64.uParse(value);
+            }
+            catch (e) {
+                return `${value} out of range`;
+            }
+            return true;
+    }
+}
 function reasonSingular(field, val, details) {
     details =
         typeof details == "string" ? `: ${details}` : `, got ${formatVal(val)}`;
@@ -141,3 +230,31 @@ function formatReflectMap(field) {
             return `ReflectMap (${ScalarType[field.mapKey]}, ${ScalarType[field.scalar]})`;
     }
 }
+function scalarTypeDescription(scalar) {
+    switch (scalar) {
+        case ScalarType.STRING:
+            return "string";
+        case ScalarType.BOOL:
+            return "boolean";
+        case ScalarType.INT64:
+        case ScalarType.SINT64:
+        case ScalarType.SFIXED64:
+            return "bigint (int64)";
+        case ScalarType.UINT64:
+        case ScalarType.FIXED64:
+            return "bigint (uint64)";
+        case ScalarType.BYTES:
+            return "Uint8Array";
+        case ScalarType.DOUBLE:
+            return "number (float64)";
+        case ScalarType.FLOAT:
+            return "number (float32)";
+        case ScalarType.FIXED32:
+        case ScalarType.UINT32:
+            return "number (uint32)";
+        case ScalarType.INT32:
+        case ScalarType.SFIXED32:
+        case ScalarType.SINT32:
+            return "number (int32)";
+    }
+}

package/dist/esm/reflect/reflect-types.d.ts

@@ -1,32 +1,151 @@
-import type { DescField, DescMessage, DescOneof } from "../desc-types.js";
+import { type DescField, type DescMessage, type DescOneof } from "../descriptors.js";
 import { FieldError } from "./error.js";
 import { unsafeLocal } from "./unsafe.js";
 import type { Message, UnknownField } from "../types.js";
-import type { LongType, ScalarValue } from "./scalar.js";
+import type { ScalarValue } from "./scalar.js";
+/**
+ * ReflectMessage provides dynamic access and manipulation of a message.
+ */
 export interface ReflectMessage {
+    /**
+     * The underlying message instance.
+     */
     readonly message: Message;
+    /**
+     * The descriptor for the message.
+     */
     readonly desc: DescMessage;
+    /**
+     * The fields of the message. This is a shortcut to message.fields.
+     */
     readonly fields: readonly DescField[];
+    /**
+     * The fields of the message, sorted by field number ascending.
+     */
     readonly sortedFields: readonly DescField[];
+    /**
+     * Oneof groups of the message. This is a shortcut to message.oneofs.
+     */
     readonly oneofs: readonly DescOneof[];
+    /**
+     * Fields and oneof groups for this message. This is a shortcut to message.members.
+     */
     readonly members: readonly (DescField | DescOneof)[];
+    /**
+     * Find a field by number.
+     */
     findNumber(number: number): DescField | undefined;
+    /**
+     * Returns true if the field is set.
+     *
+     * - Scalar and enum fields with implicit presence (proto3):
+     *   Set if not a zero value.
+     *
+     * - Scalar and enum fields with explicit presence (proto2, oneof):
+     *   Set if a value was set when creating or parsing the message, or when a
+     *   value was assigned to the field's property.
+     *
+     * - Message fields:
+     *   Set if the property is not undefined.
+     *
+     * - List and map fields:
+     *   Set if not empty.
+     */
     isSet(field: DescField): boolean;
+    /**
+     * Resets the field, so that isSet() will return false.
+     */
     clear(field: DescField): void;
+    /**
+     * Return the selected field of a oneof group.
+     */
     oneofCase(oneof: DescOneof): DescField | undefined;
+    /**
+     * Returns the field value. Values are converted or wrapped to make it easier
+     * to manipulate messages.
+     *
+     * - Scalar fields:
+     *   Returns the value, but converts 64-bit integer fields with the option
+     *   `jstype=JS_STRING` to a bigint value.
+     *   If the field is not set, the default value is returned. If no default
+     *   value is set, the zero value is returned.
+     *
+     * - Enum fields:
+     *   Returns the numeric value. If the field is not set, the default value is
+     *   returned. If no default value is set, the zero value is returned.
+     *
+     * - Message fields:
+     *   Returns a ReflectMessage. If the field is not set, a new message is
+     *   returned, but not set on the field.
+     *
+     * - List fields:
+     *   Returns a ReflectList object.
+     *
+     * - Map fields:
+     *   Returns a ReflectMap object.
+     *
+     * Note that get() never returns `undefined`. To determine whether a field is
+     * set, use isSet().
+     */
     get<Field extends DescField>(field: Field): ReflectGetValue<Field>;
+    /**
+     * Set a field value.
+     *
+     * Expects values in the same form that get() returns:
+     *
+     * - Scalar fields:
+     *   64-bit integer fields with the option `jstype=JS_STRING` as a bigint value.
+     *
+     * - Message fields:
+     *   ReflectMessage.
+     *
+     * - List fields:
+     *   ReflectList.
+     *
+     * - Map fields:
+     *   ReflectMap.
+     *
+     * Returns an error if the value is invalid for the field. `undefined` is not
+     * a valid value. To reset a field, use clear().
+     */
     set<Field extends DescField>(field: Field, value: ReflectSetValue<Field>): FieldError | undefined;
+    /**
+     * Add an item to a list field.
+     */
     addListItem<Field extends DescField & {
         fieldKind: "list";
-    }>(field: Field, value: NewListItem<Field>): FieldError | undefined;
+    }>(field: Field, value: ReflectAddListItemValue<Field>): FieldError | undefined;
+    /**
+     * Set a map entry.
+     */
     setMapEntry<Field extends DescField & {
         fieldKind: "map";
-    }>(field: Field, key: MapEntryKey, value: NewMapEntryValue<Field>): FieldError | undefined;
+    }>(field: Field, key: MapEntryKey, value: ReflectSetMapEntryValue<Field>): FieldError | undefined;
+    /**
+     * Returns the unknown fields of the message.
+     */
     getUnknown(): UnknownField[] | undefined;
+    /**
+     * Sets the unknown fields of the message, overwriting any previous values.
+     */
     setUnknown(value: UnknownField[]): void;
     [unsafeLocal]: Message;
 }
+/**
+ * ReflectList provides dynamic access and manipulation of a list field on a
+ * message.
+ *
+ * ReflectList is iterable - you can loop through all items with a for...of loop.
+ *
+ * Values are converted or wrapped to make it easier to manipulate them:
+ * - Scalar 64-bit integer fields with the option `jstype=JS_STRING` are
+ *   converted to bigint.
+ * - Messages are wrapped in a ReflectMessage.
+ */
 export interface ReflectList<V = unknown> extends Iterable<V> {
+    /**
+     * Returns the list field.
+     */
     field(): DescField & {
         fieldKind: "list";
     };
@@ -60,7 +179,21 @@ export interface ReflectList<V = unknown> extends Iterable<V> {
     values(): IterableIterator<V>;
     [unsafeLocal]: unknown[];
 }
+/**
+ * ReflectMap provides dynamic access and manipulation of a map field on a
+ * message.
+ *
+ * ReflectMap is iterable - you can loop through all entries with a for...of loop.
+ *
+ * Keys and values are converted or wrapped to make it easier to manipulate them:
+ * - A map field is a record object on a message, where keys are always strings.
+ *   ReflectMap converts keys to their closest possible type in TypeScript.
+ * - Messages are wrapped in a ReflectMessage.
+ */
 export interface ReflectMap<K extends MapEntryKey = MapEntryKey, V = unknown> extends ReadonlyMap<K, V> {
+    /**
+     * Returns the map field.
+     */
     field(): DescField & {
         fieldKind: "map";
     };
@@ -80,9 +213,15 @@ export interface ReflectMap<K extends MapEntryKey = MapEntryKey, V = unknown> ex
     clear(): void;
     [unsafeLocal]: Record<string, unknown>;
 }
+/**
+ * A ReflectMap key.
+ */
 export type MapEntryKey = string | number | bigint | boolean;
 type enumVal = number;
-type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
+/**
+ * The return type of ReflectMessage.get()
+ */
+export type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
     fieldKind: "map";
 } ? (Field extends {
     mapKind: "message";
@@ -91,29 +230,35 @@ type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
 } ? ReflectMap<MapEntryKey, enumVal> : Field extends {
     mapKind: "scalar";
     scalar: infer T;
-} ? ReflectMap<MapEntryKey, ScalarValue<T, LongType.BIGINT>> : never) : Field extends {
+} ? ReflectMap<MapEntryKey, ScalarValue<T>> : never) : Field extends {
     fieldKind: "list";
 } ? ReflectList : Field extends {
     fieldKind: "enum";
-} ? number | undefined : Field extends {
+} ? number : Field extends {
     fieldKind: "message";
 } ? ReflectMessage : Field extends {
     fieldKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T> | undefined : never);
-type ReflectSetValue<Field extends DescField = DescField> = (Field extends {
+} ? ScalarValue<T> : never);
+/**
+ * The type of the "value" argument of ReflectMessage.set()
+ */
+export type ReflectSetValue<Field extends DescField = DescField> = (Field extends {
     fieldKind: "map";
 } ? ReflectMap : Field extends {
     fieldKind: "list";
 } ? ReflectList : Field extends {
     fieldKind: "enum";
-} ? number | undefined : Field extends {
+} ? number : Field extends {
     fieldKind: "message";
 } ? ReflectMessage : Field extends {
     fieldKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T> | undefined : never);
-type NewListItem<Field extends DescField & {
+} ? ScalarValue<T> : never);
+/**
+ * The type of the "value" argument of ReflectMessage.addListItem()
+ */
+export type ReflectAddListItemValue<Field extends DescField & {
     fieldKind: "list";
 }> = (Field extends {
     listKind: "scalar";
@@ -123,7 +268,10 @@ type NewListItem<Field extends DescField & {
 } ? enumVal : Field extends {
     listKind: "message";
 } ? ReflectMessage : never);
-type NewMapEntryValue<Field extends DescField & {
+/**
+ * The type of the "value" argument of ReflectMessage.setMapEntry()
+ */
+export type ReflectSetMapEntryValue<Field extends DescField & {
     fieldKind: "map";
 }> = (Field extends {
     mapKind: "enum";
@@ -132,5 +280,5 @@ type NewMapEntryValue<Field extends DescField & {
 } ? ReflectMessage : Field extends {
     mapKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T, LongType.BIGINT> : never);
+} ? ScalarValue<T> : never);
 export {};

package/dist/esm/reflect/reflect-types.js

@@ -11,5 +11,6 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
+import {} from "../descriptors.js";
 import { FieldError } from "./error.js";
 import { unsafeLocal } from "./unsafe.js";