@bufbuild/protobuf 2.2.5 → 2.3.0

package/dist/esm/reflect/index.js

@@ -17,4 +17,5 @@ export * from "./nested-types.js";
 export * from "./reflect.js";
 export * from "./reflect-types.js";
 export * from "./scalar.js";
+export * from "./path.js";
 export { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";

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

@@ -1,3 +1,11 @@
+import type { AnyDesc } from "../descriptors.js";
+/**
+ * Return a fully-qualified name for a Protobuf descriptor.
+ * For a file descriptor, return the original file path.
+ *
+ * See https://protobuf.com/docs/language-spec#fully-qualified-names
+ */
+export declare function qualifiedName(desc: AnyDesc): string;
 /**
  * Converts snake_case to protoCamelCase according to the convention
  * used by protoc to convert a field name to a JSON name.

package/dist/esm/reflect/names.js

@@ -11,6 +11,33 @@
 // 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.
+/**
+ * Return a fully-qualified name for a Protobuf descriptor.
+ * For a file descriptor, return the original file path.
+ *
+ * See https://protobuf.com/docs/language-spec#fully-qualified-names
+ */
+export function qualifiedName(desc) {
+    switch (desc.kind) {
+        case "field":
+        case "oneof":
+        case "rpc":
+            return desc.parent.typeName + "." + desc.name;
+        case "enum_value": {
+            const p = desc.parent.parent
+                ? desc.parent.parent.typeName
+                : desc.parent.file.proto.package;
+            return p + (p.length > 0 ? "." : "") + desc.name;
+        }
+        case "service":
+        case "message":
+        case "enum":
+        case "extension":
+            return desc.typeName;
+        case "file":
+            return desc.proto.name;
+    }
+}
 /**
  * Converts snake_case to protoCamelCase according to the convention
  * used by protoc to convert a field name to a JSON name.

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

@@ -0,0 +1,107 @@
+import { type DescExtension, type DescField, type DescMessage, type DescOneof } from "../descriptors.js";
+import type { Registry } from "../registry.js";
+/**
+ * A path to a (nested) member of a Protobuf message, such as a field, oneof,
+ * extension, list element, or map entry.
+ *
+ * Note that we may add additional types to this union in the future to support
+ * more use cases.
+ */
+export type Path = (DescField | DescExtension | DescOneof | {
+    kind: "list_sub";
+    index: number;
+} | {
+    kind: "map_sub";
+    key: string | number | bigint | boolean;
+})[];
+/**
+ * Builds a Path.
+ */
+export type PathBuilder = {
+    /**
+     * The root message of the path.
+     */
+    readonly schema: DescMessage;
+    /**
+     * Add field access.
+     *
+     * Throws an InvalidPathError if the field cannot be added to the path.
+     */
+    field(field: DescField): PathBuilder;
+    /**
+     * Access a oneof.
+     *
+     * Throws an InvalidPathError if the oneof cannot be added to the path.
+     *
+     */
+    oneof(oneof: DescOneof): PathBuilder;
+    /**
+     * Access an extension.
+     *
+     * Throws an InvalidPathError if the extension cannot be added to the path.
+     */
+    extension(extension: DescExtension): PathBuilder;
+    /**
+     * Access a list field by index.
+     *
+     * Throws an InvalidPathError if the list access cannot be added to the path.
+     */
+    list(index: number): PathBuilder;
+    /**
+     * Access a map field by key.
+     *
+     * Throws an InvalidPathError if the map access cannot be added to the path.
+     */
+    map(key: string | number | bigint | boolean): PathBuilder;
+    /**
+     * Append a path.
+     *
+     * Throws an InvalidPathError if the path cannot be added.
+     */
+    add(path: Path | PathBuilder): PathBuilder;
+    /**
+     * Return the path.
+     */
+    toPath(): Path;
+    /**
+     * Create a copy of this builder.
+     */
+    clone(): PathBuilder;
+    /**
+     * Get the current container - a list, map, or message.
+     */
+    getLeft(): DescMessage | (DescField & {
+        fieldKind: "list";
+    }) | (DescField & {
+        fieldKind: "map";
+    }) | undefined;
+};
+/**
+ * Create a PathBuilder.
+ */
+export declare function buildPath(schema: DescMessage): PathBuilder;
+/**
+ * Parse a Path from a string.
+ *
+ * Throws an InvalidPathError if the path is invalid.
+ *
+ * Note that a Registry must be provided via the options argument to parse
+ * paths that refer to an extension.
+ */
+export declare function parsePath(schema: DescMessage, path: string, options?: {
+    registry?: Registry;
+}): Path;
+/**
+ * Stringify a path.
+ */
+export declare function pathToString(path: Path): string;
+/**
+ * InvalidPathError is thrown for invalid Paths, for example during parsing from
+ * a string, or when a new Path is built.
+ */
+export declare class InvalidPathError extends Error {
+    name: string;
+    readonly schema: DescMessage;
+    readonly path: Path | string;
+    constructor(schema: DescMessage, message: string, path: string | Path);
+}

package/dist/esm/reflect/path.js

@@ -0,0 +1,369 @@
+// Copyright 2021-2025 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// 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, } from "../descriptors.js";
+/**
+ * Create a PathBuilder.
+ */
+export function buildPath(schema) {
+    return new PathBuilderImpl(schema, schema, []);
+}
+/**
+ * Parse a Path from a string.
+ *
+ * Throws an InvalidPathError if the path is invalid.
+ *
+ * Note that a Registry must be provided via the options argument to parse
+ * paths that refer to an extension.
+ */
+export function parsePath(schema, path, options) {
+    var _a, _b;
+    const builder = new PathBuilderImpl(schema, schema, []);
+    const err = (message, i) => new InvalidPathError(schema, message + " at column " + (i + 1), path);
+    for (let i = 0; i < path.length;) {
+        const token = nextToken(i, path);
+        const left = builder.getLeft();
+        let right = undefined;
+        if ("field" in token) {
+            right =
+                (left === null || left === void 0 ? void 0 : left.kind) != "message"
+                    ? undefined
+                    : ((_a = left.fields.find((field) => field.name === token.field)) !== null && _a !== void 0 ? _a : left.oneofs.find((oneof) => oneof.name === token.field));
+            if (!right) {
+                throw err(`Unknown field "${token.field}"`, i);
+            }
+        }
+        else if ("ext" in token) {
+            right = (_b = options === null || options === void 0 ? void 0 : options.registry) === null || _b === void 0 ? void 0 : _b.getExtension(token.ext);
+            if (!right) {
+                throw err(`Unknown extension "${token.ext}"`, i);
+            }
+        }
+        else if ("val" in token) {
+            // list or map
+            right =
+                (left === null || left === void 0 ? void 0 : left.kind) == "field" &&
+                    left.fieldKind == "list" &&
+                    typeof token.val == "bigint"
+                    ? { kind: "list_sub", index: Number(token.val) }
+                    : { kind: "map_sub", key: token.val };
+        }
+        else if ("err" in token) {
+            throw err(token.err, token.i);
+        }
+        if (right) {
+            try {
+                builder.add([right]);
+            }
+            catch (e) {
+                throw err(e instanceof InvalidPathError ? e.message : String(e), i);
+            }
+        }
+        i = token.i;
+    }
+    return builder.toPath();
+}
+/**
+ * Stringify a path.
+ */
+export function pathToString(path) {
+    const str = [];
+    for (const ele of path) {
+        switch (ele.kind) {
+            case "field":
+            case "oneof":
+                if (str.length > 0) {
+                    str.push(".");
+                }
+                str.push(ele.name);
+                break;
+            case "extension":
+                str.push("[", ele.typeName, "]");
+                break;
+            case "list_sub":
+                str.push("[", ele.index, "]");
+                break;
+            case "map_sub":
+                if (typeof ele.key == "string") {
+                    str.push('["', ele.key
+                        .split("\\")
+                        .join("\\\\")
+                        .split('"')
+                        .join('\\"')
+                        .split("\r")
+                        .join("\\r")
+                        .split("\n")
+                        .join("\\n"), '"]');
+                }
+                else {
+                    str.push("[", ele.key, "]");
+                }
+                break;
+        }
+    }
+    return str.join("");
+}
+/**
+ * InvalidPathError is thrown for invalid Paths, for example during parsing from
+ * a string, or when a new Path is built.
+ */
+export class InvalidPathError extends Error {
+    constructor(schema, message, path) {
+        super(message);
+        this.name = "InvalidPathError";
+        this.schema = schema;
+        this.path = path;
+        // see https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-2.html#example
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+class PathBuilderImpl {
+    constructor(schema, left, path) {
+        this.schema = schema;
+        this.left = left;
+        this.path = path;
+    }
+    getLeft() {
+        return this.left;
+    }
+    field(field) {
+        return this.push(field);
+    }
+    oneof(oneof) {
+        return this.push(oneof);
+    }
+    extension(extension) {
+        return this.push(extension);
+    }
+    list(index) {
+        return this.push({ kind: "list_sub", index });
+    }
+    map(key) {
+        return this.push({ kind: "map_sub", key });
+    }
+    add(pathOrBuilder) {
+        const path = Array.isArray(pathOrBuilder)
+            ? pathOrBuilder
+            : pathOrBuilder.toPath();
+        const l = this.path.length;
+        try {
+            for (const ele of path) {
+                this.push(ele);
+            }
+        }
+        catch (e) {
+            // undo pushes
+            this.path.splice(l);
+            throw e;
+        }
+        return this;
+    }
+    toPath() {
+        return this.path.concat();
+    }
+    clone() {
+        return new PathBuilderImpl(this.schema, this.left, this.path.concat());
+    }
+    push(ele) {
+        switch (ele.kind) {
+            case "field":
+                if (!this.left ||
+                    this.left.kind != "message" ||
+                    this.left.typeName != ele.parent.typeName) {
+                    throw this.err("field access");
+                }
+                this.path.push(ele);
+                this.left =
+                    ele.fieldKind == "message"
+                        ? ele.message
+                        : ele.fieldKind == "list" || ele.fieldKind == "map"
+                            ? ele
+                            : undefined;
+                return this;
+            case "oneof":
+                if (!this.left ||
+                    this.left.kind != "message" ||
+                    this.left.typeName != ele.parent.typeName) {
+                    throw this.err("oneof access");
+                }
+                this.path.push(ele);
+                this.left = undefined;
+                return this;
+            case "extension":
+                if (!this.left ||
+                    this.left.kind != "message" ||
+                    this.left.typeName != ele.extendee.typeName) {
+                    throw this.err("extension access");
+                }
+                this.path.push(ele);
+                this.left = ele.fieldKind == "message" ? ele.message : undefined;
+                return this;
+            case "list_sub":
+                if (!this.left ||
+                    this.left.kind != "field" ||
+                    this.left.fieldKind != "list") {
+                    throw this.err("list access");
+                }
+                if (ele.index < 0 || !Number.isInteger(ele.index)) {
+                    throw this.err("list index");
+                }
+                this.path.push(ele);
+                this.left =
+                    this.left.listKind == "message" ? this.left.message : undefined;
+                return this;
+            case "map_sub":
+                if (!this.left ||
+                    this.left.kind != "field" ||
+                    this.left.fieldKind != "map") {
+                    throw this.err("map access");
+                }
+                if (!checkKeyType(ele.key, this.left.mapKey)) {
+                    throw this.err("map key");
+                }
+                this.path.push(ele);
+                this.left =
+                    this.left.mapKind == "message" ? this.left.message : undefined;
+                return this;
+        }
+    }
+    err(what) {
+        return new InvalidPathError(this.schema, "Invalid " + what, this.path);
+    }
+}
+function checkKeyType(key, type) {
+    switch (type) {
+        case ScalarType.STRING:
+            return typeof key == "string";
+        case ScalarType.INT32:
+        case ScalarType.UINT32:
+        case ScalarType.SINT32:
+        case ScalarType.SFIXED32:
+        case ScalarType.FIXED32:
+            return typeof key == "number";
+        case ScalarType.UINT64:
+        case ScalarType.INT64:
+        case ScalarType.FIXED64:
+        case ScalarType.SFIXED64:
+        case ScalarType.SINT64:
+            return typeof key == "bigint";
+        case ScalarType.BOOL:
+            return typeof key == "boolean";
+    }
+}
+function nextToken(i, path) {
+    const re_extension = /^[A-Za-z_][A-Za-z_0-9]*(?:\.[A-Za-z_][A-Za-z_0-9]*)*$/;
+    const re_field = /^[A-Za-z_][A-Za-z_0-9]*$/;
+    if (path[i] == "[") {
+        i++;
+        while (path[i] == " ") {
+            // skip leading whitespace
+            i++;
+        }
+        if (i >= path.length) {
+            return { err: "Premature end", i: path.length - 1 };
+        }
+        let token;
+        if (path[i] == `"`) {
+            // string literal
+            i++;
+            let val = "";
+            for (;;) {
+                if (path[i] == `"`) {
+                    // end of string literal
+                    i++;
+                    break;
+                }
+                if (path[i] == "\\") {
+                    switch (path[i + 1]) {
+                        case `"`:
+                        case "\\":
+                            val += path[i + 1];
+                            break;
+                        case "r":
+                            val += "\r";
+                            break;
+                        case "n":
+                            val += "\n";
+                            break;
+                        default:
+                            return { err: "Invalid escape sequence", i };
+                    }
+                    i++;
+                }
+                else {
+                    val += path[i];
+                }
+                if (i >= path.length) {
+                    return { err: "Premature end of string", i: path.length - 1 };
+                }
+                i++;
+            }
+            token = { val };
+        }
+        else if (path[i].match(/\d/)) {
+            // integer literal
+            const start = i;
+            while (i < path.length && /\d/.test(path[i])) {
+                i++;
+            }
+            token = { val: BigInt(path.substring(start, i)) };
+        }
+        else if (path[i] == "]") {
+            return { err: "Premature ]", i };
+        }
+        else {
+            // extension identifier or bool literal
+            const start = i;
+            while (i < path.length && path[i] != " " && path[i] != "]") {
+                i++;
+            }
+            const name = path.substring(start, i);
+            if (name === "true") {
+                token = { val: true };
+            }
+            else if (name === "false") {
+                token = { val: false };
+            }
+            else if (re_extension.test(name)) {
+                token = { ext: name };
+            }
+            else {
+                return { err: "Invalid ident", i: start };
+            }
+        }
+        while (path[i] == " ") {
+            // skip trailing whitespace
+            i++;
+        }
+        if (path[i] != "]") {
+            return { err: "Missing ]", i };
+        }
+        i++;
+        return Object.assign(Object.assign({}, token), { i });
+    }
+    // field identifier
+    if (i > 0) {
+        if (path[i] != ".") {
+            return { err: `Expected "."`, i };
+        }
+        i++;
+    }
+    const start = i;
+    while (i < path.length && path[i] != "." && path[i] != "[") {
+        i++;
+    }
+    const field = path.substring(start, i);
+    return re_field.test(field)
+        ? { field, i }
+        : { err: "Invalid ident", i: start };
+}

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

@@ -136,7 +136,7 @@ function checkScalarValue(value, scalar) {
                     protoInt64.parse(value);
                     return true;
                 }
-                catch (e) {
+                catch (_) {
                     return `${value} out of range`;
                 }
             }
@@ -151,7 +151,7 @@ function checkScalarValue(value, scalar) {
                     protoInt64.uParse(value);
                     return true;
                 }
-                catch (e) {
+                catch (_) {
                     return `${value} out of range`;
                 }
             }
@@ -164,7 +164,7 @@ function reasonSingular(field, val, details) {
     if (field.scalar !== undefined) {
         return `expected ${scalarTypeDescription(field.scalar)}` + details;
     }
-    else if (field.enum !== undefined) {
+    if (field.enum !== undefined) {
         return `expected ${field.enum.toString()}` + details;
     }
     return `expected ${formatReflectMessage(field.message)}` + details;

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

@@ -1,4 +1,4 @@
-import { type DescField, type DescMessage, type DescOneof } from "../descriptors.js";
+import type { DescField, DescMessage, DescOneof } from "../descriptors.js";
 import { unsafeLocal } from "./unsafe.js";
 import type { Message, UnknownField } from "../types.js";
 import type { ScalarValue } from "./scalar.js";

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

@@ -11,5 +11,4 @@
 // 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 { unsafeLocal } from "./unsafe.js";

package/dist/esm/reflect/reflect.js

@@ -37,7 +37,9 @@ check = true) {
 class ReflectMessageImpl {
     get sortedFields() {
         var _a;
-        return ((_a = this._sortedFields) !== null && _a !== void 0 ? _a : (this._sortedFields = this.desc.fields
+        return ((_a = this._sortedFields) !== null && _a !== void 0 ? _a : 
+        // biome-ignore lint/suspicious/noAssignInExpressions: no
+        (this._sortedFields = this.desc.fields
             .concat()
             .sort((a, b) => a.number - b.number)));
     }
@@ -77,14 +79,17 @@ class ReflectMessageImpl {
                 // eslint-disable-next-line no-case-declarations
                 let list = this.lists.get(field);
                 if (!list || list[unsafeLocal] !== value) {
-                    this.lists.set(field, (list = new ReflectListImpl(field, value, this.check)));
+                    this.lists.set(field, 
+                    // biome-ignore lint/suspicious/noAssignInExpressions: no
+                    (list = new ReflectListImpl(field, value, this.check)));
                 }
                 return list;
             case "map":
-                // eslint-disable-next-line no-case-declarations
                 let map = this.maps.get(field);
                 if (!map || map[unsafeLocal] !== value) {
-                    this.maps.set(field, (map = new ReflectMapImpl(field, value, this.check)));
+                    this.maps.set(field, 
+                    // biome-ignore lint/suspicious/noAssignInExpressions: no
+                    (map = new ReflectMapImpl(field, value, this.check)));
                 }
                 return map;
             case "message":
@@ -407,7 +412,6 @@ function mapKeyToReflect(key, type) {
     return key;
 }
 function longToReflect(field, value) {
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
     switch (field.scalar) {
         case ScalarType.INT64:
         case ScalarType.SFIXED64:
@@ -430,7 +434,6 @@ function longToReflect(field, value) {
     return value;
 }
 function longToLocal(field, value) {
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
     switch (field.scalar) {
         case ScalarType.INT64:
         case ScalarType.SFIXED64:
@@ -491,7 +494,6 @@ function wktValueToReflect(json) {
         $typeName: "google.protobuf.Value",
         kind: { case: undefined },
     };
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check -- invalid input is unselected kind
     switch (typeof json) {
         case "number":
             value.kind = { case: "numberValue", value: json };

package/dist/esm/reflect/scalar.js

@@ -37,7 +37,6 @@ export function scalarEquals(type, a, b) {
         return true;
     }
     // Special case 64-bit integers - we support number, string and bigint representation.
-    // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
     switch (type) {
         case ScalarType.UINT64:
         case ScalarType.FIXED64:
@@ -60,10 +59,6 @@ export function scalarZeroValue(type, longAsString) {
             return "";
         case ScalarType.BOOL:
             return false;
-        default:
-            // Handles INT32, UINT32, SINT32, FIXED32, SFIXED32.
-            // We do not use individual cases to save a few bytes code size.
-            return 0;
         case ScalarType.DOUBLE:
         case ScalarType.FLOAT:
             return 0.0;
@@ -75,6 +70,10 @@ export function scalarZeroValue(type, longAsString) {
             return (longAsString ? "0" : protoInt64.zero);
         case ScalarType.BYTES:
             return new Uint8Array(0);
+        default:
+            // Handles INT32, UINT32, SINT32, FIXED32, SFIXED32.
+            // We do not use individual cases to save a few bytes code size.
+            return 0;
     }
 }
 /**

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

@@ -5,15 +5,13 @@ export declare const unsafeLocal: unique symbol;
  *
  * @private
  */
-export declare function unsafeOneofCase(target: Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
-oneof: DescOneof): DescField | undefined;
+export declare function unsafeOneofCase(target: Record<string, any>, oneof: DescOneof): DescField | undefined;
 /**
  * Returns true if the field is set.
  *
  * @private
  */
-export declare function unsafeIsSet(target: Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
-field: DescField): boolean;
+export declare function unsafeIsSet(target: Record<string, any>, field: DescField): boolean;
 /**
  * Returns true if the field is set, but only for singular fields with explicit
  * presence (proto2).
@@ -38,5 +36,4 @@ export declare function unsafeSet(target: Record<string, unknown>, field: DescFi
  *
  * @private
  */
-export declare function unsafeClear(target: Record<string, any>, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
-field: DescField): void;
+export declare function unsafeClear(target: Record<string, any>, field: DescField): void;