@bufbuild/protobuf 1.8.0 → 2.0.0-alpha.1

package/dist/{esm → cjs/reflect}/scalar.d.ts

@@ -50,4 +50,24 @@ export declare enum LongType {
 /**
  * ScalarValue maps from a scalar field type to a TypeScript value type.
  */
-export type ScalarValue<T = ScalarType, L extends LongType = LongType.STRING | LongType.BIGINT> = T extends ScalarType.STRING ? string : T extends ScalarType.INT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.SINT32 ? number : T extends ScalarType.FIXED32 ? number : T extends ScalarType.SFIXED32 ? number : T extends ScalarType.FLOAT ? number : T extends ScalarType.DOUBLE ? number : T extends ScalarType.INT64 ? (L extends LongType.STRING ? string : bigint) : T extends ScalarType.SINT64 ? (L extends LongType.STRING ? string : bigint) : T extends ScalarType.SFIXED64 ? (L extends LongType.STRING ? string : bigint) : T extends ScalarType.UINT64 ? (L extends LongType.STRING ? string : bigint) : T extends ScalarType.FIXED64 ? (L extends LongType.STRING ? string : bigint) : T extends ScalarType.BOOL ? boolean : T extends ScalarType.BYTES ? Uint8Array : never;
+export type ScalarValue<T = ScalarType, L extends LongType = LongType.STRING | LongType.BIGINT> = T extends ScalarType.STRING ? string : T extends ScalarType.INT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.SINT32 ? number : T extends ScalarType.FIXED32 ? number : T extends ScalarType.SFIXED32 ? number : T extends ScalarType.FLOAT ? number : T extends ScalarType.DOUBLE ? number : T extends ScalarType.INT64 ? L extends LongType.STRING ? string : bigint : T extends ScalarType.SINT64 ? L extends LongType.STRING ? string : bigint : T extends ScalarType.SFIXED64 ? L extends LongType.STRING ? string : bigint : T extends ScalarType.UINT64 ? L extends LongType.STRING ? string : bigint : T extends ScalarType.FIXED64 ? L extends LongType.STRING ? string : bigint : T extends ScalarType.BOOL ? boolean : T extends ScalarType.BYTES ? Uint8Array : never;
+/**
+ * Returns true if both scalar values are equal.
+ */
+export declare function scalarEquals(type: ScalarType, a: string | boolean | number | bigint | Uint8Array | undefined, b: string | boolean | number | bigint | Uint8Array | undefined): boolean;
+/**
+ * Returns the zero value for the given scalar type.
+ */
+export declare function scalarZeroValue<T extends ScalarType, L extends LongType>(type: T, longType: L): ScalarValue<T, L>;
+/**
+ * Returns true for a zero-value. For example, an integer has the zero-value `0`,
+ * a boolean is `false`, a string is `""`, and bytes is an empty Uint8Array.
+ *
+ * In proto3, zero-values are not written to the wire, unless the field is
+ * optional or repeated.
+ */
+export declare function isScalarZeroValue(type: ScalarType, value: unknown): boolean;
+export type InvalidScalarValueErr = false | "invalid UTF8" | `${string} out of range`;
+export declare function checkScalarValue(value: unknown, scalar: ScalarType): true | InvalidScalarValueErr;
+export declare function scalarTypeDescription(scalar: ScalarType): string;
+export declare function scalarTypeScriptType(scalar: ScalarType, long: LongType): "string" | "boolean" | "bigint" | "bigint | string" | "Uint8Array" | "number";

package/dist/cjs/reflect/scalar.js

@@ -0,0 +1,298 @@
+"use strict";
+// Copyright 2021-2024 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scalarTypeScriptType = exports.scalarTypeDescription = exports.checkScalarValue = exports.isScalarZeroValue = exports.scalarZeroValue = exports.scalarEquals = exports.LongType = exports.ScalarType = void 0;
+const proto_int64_js_1 = require("../proto-int64.js");
+const text_encoding_js_1 = require("../wire/text-encoding.js");
+/**
+ * Scalar value types. This is a subset of field types declared by protobuf
+ * enum google.protobuf.FieldDescriptorProto.Type The types GROUP and MESSAGE
+ * are omitted, but the numerical values are identical.
+ */
+var ScalarType;
+(function (ScalarType) {
+    // 0 is reserved for errors.
+    // Order is weird for historical reasons.
+    ScalarType[ScalarType["DOUBLE"] = 1] = "DOUBLE";
+    ScalarType[ScalarType["FLOAT"] = 2] = "FLOAT";
+    // Not ZigZag encoded.  Negative numbers take 10 bytes.  Use TYPE_SINT64 if
+    // negative values are likely.
+    ScalarType[ScalarType["INT64"] = 3] = "INT64";
+    ScalarType[ScalarType["UINT64"] = 4] = "UINT64";
+    // Not ZigZag encoded.  Negative numbers take 10 bytes.  Use TYPE_SINT32 if
+    // negative values are likely.
+    ScalarType[ScalarType["INT32"] = 5] = "INT32";
+    ScalarType[ScalarType["FIXED64"] = 6] = "FIXED64";
+    ScalarType[ScalarType["FIXED32"] = 7] = "FIXED32";
+    ScalarType[ScalarType["BOOL"] = 8] = "BOOL";
+    ScalarType[ScalarType["STRING"] = 9] = "STRING";
+    // Tag-delimited aggregate.
+    // Group type is deprecated and not supported in proto3. However, Proto3
+    // implementations should still be able to parse the group wire format and
+    // treat group fields as unknown fields.
+    // TYPE_GROUP = 10,
+    // TYPE_MESSAGE = 11,  // Length-delimited aggregate.
+    // New in version 2.
+    ScalarType[ScalarType["BYTES"] = 12] = "BYTES";
+    ScalarType[ScalarType["UINT32"] = 13] = "UINT32";
+    // TYPE_ENUM = 14,
+    ScalarType[ScalarType["SFIXED32"] = 15] = "SFIXED32";
+    ScalarType[ScalarType["SFIXED64"] = 16] = "SFIXED64";
+    ScalarType[ScalarType["SINT32"] = 17] = "SINT32";
+    ScalarType[ScalarType["SINT64"] = 18] = "SINT64";
+})(ScalarType || (exports.ScalarType = ScalarType = {}));
+/**
+ * JavaScript representation of fields with 64 bit integral types (int64, uint64,
+ * sint64, fixed64, sfixed64).
+ *
+ * This is a subset of google.protobuf.FieldOptions.JSType, which defines JS_NORMAL,
+ * JS_STRING, and JS_NUMBER. Protobuf-ES uses BigInt by default, but will use
+ * String if `[jstype = JS_STRING]` is specified.
+ *
+ * ```protobuf
+ * uint64 field_a = 1; // BigInt
+ * uint64 field_b = 2 [jstype = JS_NORMAL]; // BigInt
+ * uint64 field_b = 2 [jstype = JS_NUMBER]; // BigInt
+ * uint64 field_b = 2 [jstype = JS_STRING]; // String
+ * ```
+ */
+var LongType;
+(function (LongType) {
+    /**
+     * Use JavaScript BigInt.
+     */
+    LongType[LongType["BIGINT"] = 0] = "BIGINT";
+    /**
+     * Use JavaScript String.
+     *
+     * Field option `[jstype = JS_STRING]`.
+     */
+    LongType[LongType["STRING"] = 1] = "STRING";
+})(LongType || (exports.LongType = LongType = {}));
+/**
+ * Returns true if both scalar values are equal.
+ */
+function scalarEquals(type, a, b) {
+    if (a === b) {
+        // This correctly matches equal values except BYTES and (possibly) 64-bit integers.
+        return true;
+    }
+    // Special case BYTES - we need to compare each byte individually
+    if (type == ScalarType.BYTES) {
+        if (!(a instanceof Uint8Array) || !(b instanceof Uint8Array)) {
+            return false;
+        }
+        if (a.length !== b.length) {
+            return false;
+        }
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i]) {
+                return false;
+            }
+        }
+        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:
+        case ScalarType.INT64:
+        case ScalarType.SFIXED64:
+        case ScalarType.SINT64:
+            // Loose comparison will match between 0n, 0 and "0".
+            return a == b;
+    }
+    // Anything that hasn't been caught by strict comparison or special cased
+    // BYTES and 64-bit integers is not equal.
+    return false;
+}
+exports.scalarEquals = scalarEquals;
+/**
+ * Returns the zero value for the given scalar type.
+ */
+function scalarZeroValue(type, longType) {
+    switch (type) {
+        case ScalarType.BOOL:
+            return false;
+        case ScalarType.UINT64:
+        case ScalarType.FIXED64:
+        case ScalarType.INT64:
+        case ScalarType.SFIXED64:
+        case ScalarType.SINT64:
+            return (longType == 0 ? proto_int64_js_1.protoInt64.zero : "0");
+        case ScalarType.DOUBLE:
+        case ScalarType.FLOAT:
+            return 0.0;
+        case ScalarType.BYTES:
+            return new Uint8Array(0);
+        case ScalarType.STRING:
+            return "";
+        default:
+            // Handles INT32, UINT32, SINT32, FIXED32, SFIXED32.
+            // We do not use individual cases to save a few bytes code size.
+            return 0;
+    }
+}
+exports.scalarZeroValue = scalarZeroValue;
+/**
+ * Returns true for a zero-value. For example, an integer has the zero-value `0`,
+ * a boolean is `false`, a string is `""`, and bytes is an empty Uint8Array.
+ *
+ * In proto3, zero-values are not written to the wire, unless the field is
+ * optional or repeated.
+ */
+function isScalarZeroValue(type, value) {
+    switch (type) {
+        case ScalarType.BOOL:
+            return value === false;
+        case ScalarType.STRING:
+            return value === "";
+        case ScalarType.BYTES:
+            return value instanceof Uint8Array && !value.byteLength;
+        default:
+            return value == 0; // Loose comparison matches 0n, 0 and "0"
+    }
+}
+exports.isScalarZeroValue = isScalarZeroValue;
+const FLOAT32_MAX = 3.4028234663852886e38, FLOAT32_MIN = -3.4028234663852886e38, UINT32_MAX = 0xffffffff, INT32_MAX = 0x7fffffff, INT32_MIN = -0x80000000;
+// TODO this checks UTF-8 validity
+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 (0, text_encoding_js_1.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 {
+                proto_int64_js_1.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 {
+                proto_int64_js_1.protoInt64.uParse(value);
+            }
+            catch (e) {
+                return `${value} out of range`;
+            }
+            return true;
+    }
+}
+exports.checkScalarValue = checkScalarValue;
+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)";
+    }
+}
+exports.scalarTypeDescription = scalarTypeDescription;
+function scalarTypeScriptType(scalar, long) {
+    switch (scalar) {
+        case ScalarType.STRING:
+            return "string";
+        case ScalarType.BOOL:
+            return "boolean";
+        case ScalarType.UINT64:
+        case ScalarType.SFIXED64:
+        case ScalarType.FIXED64:
+        case ScalarType.SINT64:
+        case ScalarType.INT64:
+            return long == LongType.STRING ? "string" : "bigint";
+        case ScalarType.BYTES:
+            return "Uint8Array";
+        default:
+            return "number";
+    }
+}
+exports.scalarTypeScriptType = scalarTypeScriptType;

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

@@ -0,0 +1,58 @@
+import type { DescField, DescOneof } from "../desc-types.js";
+export declare const unsafeLocal: unique symbol;
+/**
+ * Return the selected field of a oneof group.
+ *
+ * @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;
+/**
+ * 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;
+/**
+ * Returns true if the field is set, but only for singular fields with explicit
+ * presence (proto2).
+ *
+ * @private
+ */
+export declare function unsafeIsSetExplicit(target: object, localName: string): boolean;
+/**
+ * Return a field value, respecting oneof groups.
+ *
+ * @private
+ */
+export declare function unsafeGet(target: Record<string, unknown>, field: DescField): unknown;
+/**
+ * Set a field value, respecting oneof groups.
+ *
+ * @private
+ */
+export declare function unsafeSet(target: Record<string, unknown>, field: DescField, value: unknown): void;
+/**
+ * Resets the field, so that unsafeIsSet() will return false.
+ *
+ * @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;
+/**
+ * Add an item to a list field.
+ *
+ * @private
+ */
+export declare function unsafeAddListItem(target: Record<string, unknown>, field: DescField & {
+    fieldKind: "list";
+}, value: unknown): void;
+/**
+ * Set a map entry.
+ *
+ * @private
+ */
+export declare function unsafeSetMapEntry(target: Record<string, unknown>, field: DescField & {
+    fieldKind: "map";
+}, key: string | number, value: unknown): void;

package/dist/cjs/reflect/unsafe.js

@@ -0,0 +1,171 @@
+"use strict";
+// Copyright 2021-2024 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unsafeSetMapEntry = exports.unsafeAddListItem = exports.unsafeClear = exports.unsafeSet = exports.unsafeGet = exports.unsafeIsSetExplicit = exports.unsafeIsSet = exports.unsafeOneofCase = exports.unsafeLocal = void 0;
+const names_js_1 = require("./names.js");
+const scalar_js_1 = require("./scalar.js");
+// bootstrap-inject google.protobuf.FeatureSet.FieldPresence.IMPLICIT: const $name: FeatureSet_FieldPresence.$localName = $number;
+const IMPLICIT = 2;
+exports.unsafeLocal = Symbol.for("reflect unsafe local");
+/**
+ * Return the selected field of a oneof group.
+ *
+ * @private
+ */
+function unsafeOneofCase(target, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
+oneof) {
+    const c = target[(0, names_js_1.localName)(oneof)].case;
+    if (c === undefined) {
+        return c;
+    }
+    return oneof.fields.find((f) => (0, names_js_1.localName)(f) === c);
+}
+exports.unsafeOneofCase = unsafeOneofCase;
+/**
+ * Returns true if the field is set.
+ *
+ * @private
+ */
+function unsafeIsSet(target, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
+field) {
+    const name = (0, names_js_1.localName)(field);
+    if (field.oneof) {
+        return target[(0, names_js_1.localName)(field.oneof)].case === name; // eslint-disable-line @typescript-eslint/no-unsafe-member-access
+    }
+    switch (field.fieldKind) {
+        case "message":
+            return target[name] !== undefined;
+        case "list":
+            return target[name].length > 0;
+        case "map":
+            return Object.keys(target[name]).length > 0; // eslint-disable-line @typescript-eslint/no-unsafe-argument
+        default:
+            if (field.presence == IMPLICIT) {
+                if (field.fieldKind == "enum") {
+                    return target[name] !== field.enum.values[0].number;
+                }
+                return !(0, scalar_js_1.isScalarZeroValue)(field.scalar, target[name]);
+            }
+            // EXPLICIT and LEGACY_REQUIRED
+            return (target[name] !== undefined &&
+                Object.prototype.hasOwnProperty.call(target, name));
+    }
+}
+exports.unsafeIsSet = unsafeIsSet;
+/**
+ * Returns true if the field is set, but only for singular fields with explicit
+ * presence (proto2).
+ *
+ * @private
+ */
+function unsafeIsSetExplicit(target, localName) {
+    return (Object.prototype.hasOwnProperty.call(target, localName) &&
+        target[localName] !== undefined);
+}
+exports.unsafeIsSetExplicit = unsafeIsSetExplicit;
+/**
+ * Return a field value, respecting oneof groups.
+ *
+ * @private
+ */
+function unsafeGet(target, field) {
+    const name = (0, names_js_1.localName)(field);
+    if (field.oneof) {
+        const oneof = target[(0, names_js_1.localName)(field.oneof)];
+        if (oneof.case === name) {
+            return oneof.value;
+        }
+        return undefined;
+    }
+    return target[name];
+}
+exports.unsafeGet = unsafeGet;
+/**
+ * Set a field value, respecting oneof groups.
+ *
+ * @private
+ */
+function unsafeSet(target, field, value) {
+    const name = (0, names_js_1.localName)(field);
+    if (field.oneof) {
+        target[(0, names_js_1.localName)(field.oneof)] = {
+            case: name,
+            value: value,
+        };
+    }
+    else {
+        target[name] = value;
+    }
+}
+exports.unsafeSet = unsafeSet;
+/**
+ * Resets the field, so that unsafeIsSet() will return false.
+ *
+ * @private
+ */
+function unsafeClear(target, // eslint-disable-line @typescript-eslint/no-explicit-any -- `any` is the best choice for dynamic access
+field) {
+    const name = (0, names_js_1.localName)(field);
+    if (field.oneof) {
+        const oneofLocalName = (0, names_js_1.localName)(field.oneof);
+        if (target[oneofLocalName].case === name) {
+            target[oneofLocalName] = { case: undefined };
+        }
+    }
+    else {
+        switch (field.fieldKind) {
+            case "map":
+                target[name] = {};
+                break;
+            case "list":
+                target[name] = [];
+                break;
+            case "message":
+                delete target[name];
+                break;
+            default:
+                if (field.presence == IMPLICIT) {
+                    target[name] =
+                        field.fieldKind == "enum"
+                            ? field.enum.values[0].number
+                            : (0, scalar_js_1.scalarZeroValue)(field.scalar, field.longType);
+                }
+                else {
+                    delete target[name];
+                }
+        }
+    }
+}
+exports.unsafeClear = unsafeClear;
+/**
+ * Add an item to a list field.
+ *
+ * @private
+ */
+function unsafeAddListItem(target, field, value) {
+    const name = (0, names_js_1.localName)(field);
+    target[name].push(value);
+}
+exports.unsafeAddListItem = unsafeAddListItem;
+/**
+ * Set a map entry.
+ *
+ * @private
+ */
+function unsafeSetMapEntry(target, field, key, value) {
+    const name = (0, names_js_1.localName)(field);
+    target[name][key] = value;
+}
+exports.unsafeSetMapEntry = unsafeSetMapEntry;

package/dist/cjs/to-binary.d.ts

@@ -0,0 +1,24 @@
+import type { MessageShape } from "./types.js";
+import { BinaryWriter } from "./wire/binary-encoding.js";
+import type { DescField, DescMessage } from "./desc-types.js";
+import type { ReflectMessage } from "./reflect/index.js";
+/**
+ * Options for serializing to binary data.
+ *
+ * V1 also had the option `readerFactory` for using a custom implementation to
+ * encode to binary.
+ */
+export interface BinaryWriteOptions {
+    /**
+     * Include unknown fields in the serialized output? The default behavior
+     * is to retain unknown fields and include them in the serialized output.
+     *
+     * For more details see https://developers.google.com/protocol-buffers/docs/proto3#unknowns
+     */
+    writeUnknownFields: boolean;
+}
+export declare function toBinary<Desc extends DescMessage>(messageDesc: Desc, message: MessageShape<Desc>, options?: Partial<BinaryWriteOptions>): Uint8Array;
+/**
+ * @private
+ */
+export declare function writeField(writer: BinaryWriter, opts: BinaryWriteOptions, msg: ReflectMessage, field: DescField): void;