@bufbuild/protobuf 2.11.0 → 2.12.1

package/dist/{cjs → commonjs}/from-json.js

@@ -29,38 +29,42 @@ const names_js_1 = require("./reflect/names.js");
 const base64_encoding_js_1 = require("./wire/base64-encoding.js");
 const index_js_1 = require("./wkt/index.js");
 const extensions_js_1 = require("./extensions.js");
-// Default options for parsing JSON.
-const jsonReadDefaults = {
-    ignoreUnknownFields: false,
-};
-function makeReadOptions(options) {
-    return options ? Object.assign(Object.assign({}, jsonReadDefaults), options) : jsonReadDefaults;
+function makeReadContext(options) {
+    return Object.assign(Object.assign({ ignoreUnknownFields: false, recursionLimit: 100 }, options), { depth: 0 });
 }
 /**
  * Parse a message from a JSON string.
+ *
+ * Duplicate keys are rejected.
  */
 function fromJsonString(schema, json, options) {
     return fromJson(schema, parseJsonString(json, schema.typeName), options);
 }
 /**
- * Parse a message from a JSON string, merging fields.
+ * Parse a message from a JSON string, merging fields into the target.
  *
  * Repeated fields are appended. Map entries are added, overwriting
  * existing keys.
  *
  * If a message field is already present, it will be merged with the
  * new data.
+ *
+ * Duplicate keys in the JSON are rejected, as in `fromJsonString`.
  */
 function mergeFromJsonString(schema, target, json, options) {
     return mergeFromJson(schema, target, parseJsonString(json, schema.typeName), options);
 }
 /**
  * Parse a message from a JSON value.
+ *
+ * Duplicate keys are rejected, but a value parsed by JSON.parse has already
+ * dropped duplicates (the last one wins). Use `fromJsonString` for strict
+ * duplicate-key checking.
  */
 function fromJson(schema, json, options) {
     const msg = (0, reflect_js_1.reflect)(schema);
     try {
-        readMessage(msg, json, makeReadOptions(options));
+        readMessage(msg, json, makeReadContext(options));
     }
     catch (e) {
         if ((0, error_js_1.isFieldError)(e)) {
@@ -74,17 +78,20 @@ function fromJson(schema, json, options) {
     return msg.message;
 }
 /**
- * Parse a message from a JSON value, merging fields.
+ * Parse a message from a JSON value, merging fields into the target.
  *
  * Repeated fields are appended. Map entries are added, overwriting
  * existing keys.
  *
  * If a message field is already present, it will be merged with the
  * new data.
+ *
+ * Duplicate keys are rejected as in `fromJson`; use `mergeFromJsonString`
+ * for strict checking.
  */
 function mergeFromJson(schema, target, json, options) {
     try {
-        readMessage((0, reflect_js_1.reflect)(schema, target), json, makeReadOptions(options));
+        readMessage((0, reflect_js_1.reflect)(schema, target), json, makeReadContext(options));
     }
     catch (e) {
         if ((0, error_js_1.isFieldError)(e)) {
@@ -121,82 +128,95 @@ function getJsonField(desc, jsonKey) {
     }
     return (_a = messageJsonFields.get(desc)) === null || _a === void 0 ? void 0 : _a.get(jsonKey);
 }
-function readMessage(msg, json, opts) {
+function readMessage(msg, json, ctx) {
     var _a;
-    if (tryWktFromJson(msg, json, opts)) {
+    if (++ctx.depth > ctx.recursionLimit) {
+        throw new Error(`cannot decode ${msg.desc} from JSON: maximum recursion depth of ${ctx.recursionLimit} reached`);
+    }
+    if (tryWktFromJson(msg, json, ctx)) {
+        ctx.depth--;
         return;
     }
     if (json == null || Array.isArray(json) || typeof json != "object") {
         throw new Error(`cannot decode ${msg.desc} from JSON: ${(0, reflect_check_js_1.formatVal)(json)}`);
     }
     const oneofSeen = new Map();
+    const fieldSeen = new Set();
     for (const [jsonKey, jsonValue] of Object.entries(json)) {
         const field = getJsonField(msg.desc, jsonKey);
         if (field) {
+            if (fieldSeen.has(field)) {
+                // The same field may be set by its proto name and its JSON name, or by
+                // a duplicate or unicode-escaped key that JSON.parse already collapsed.
+                // Checked before the null-skip below so that a null entry still counts.
+                throw new error_js_1.FieldError(field, "set multiple times");
+            }
+            fieldSeen.add(field);
+            if (field.oneof && jsonValue === null && field.fieldKind == "scalar") {
+                // see conformance test Required.Proto3.JsonInput.OneofFieldNull{First,Second}
+                continue;
+            }
             if (field.oneof) {
-                if (jsonValue === null && field.fieldKind == "scalar") {
-                    // see conformance test Required.Proto3.JsonInput.OneofFieldNull{First,Second}
-                    continue;
-                }
                 const seen = oneofSeen.get(field.oneof);
                 if (seen !== undefined) {
                     throw new error_js_1.FieldError(field.oneof, `oneof set multiple times by ${seen.name} and ${field.name}`);
                 }
                 oneofSeen.set(field.oneof, field);
             }
-            readField(msg, field, jsonValue, opts);
+            readField(msg, field, jsonValue, ctx);
         }
         else {
             let extension = undefined;
             if (jsonKey.startsWith("[") &&
                 jsonKey.endsWith("]") &&
                 // biome-ignore lint/suspicious/noAssignInExpressions: no
-                (extension = (_a = opts.registry) === null || _a === void 0 ? void 0 : _a.getExtension(jsonKey.substring(1, jsonKey.length - 1))) &&
+                (extension = (_a = ctx.registry) === null || _a === void 0 ? void 0 : _a.getExtension(jsonKey.substring(1, jsonKey.length - 1))) &&
                 extension.extendee.typeName === msg.desc.typeName) {
                 const [container, field, get] = (0, extensions_js_1.createExtensionContainer)(extension);
-                readField(container, field, jsonValue, opts);
+                readField(container, field, jsonValue, ctx);
                 (0, extensions_js_1.setExtension)(msg.message, extension, get());
             }
-            if (!extension && !opts.ignoreUnknownFields) {
+            if (!extension && !ctx.ignoreUnknownFields) {
                 throw new Error(`cannot decode ${msg.desc} from JSON: key "${jsonKey}" is unknown`);
             }
         }
     }
+    ctx.depth--;
 }
-function readField(msg, field, json, opts) {
+function readField(msg, field, json, ctx) {
     switch (field.fieldKind) {
         case "scalar":
             readScalarField(msg, field, json);
             break;
         case "enum":
-            readEnumField(msg, field, json, opts);
+            readEnumField(msg, field, json, ctx);
             break;
         case "message":
-            readMessageField(msg, field, json, opts);
+            readMessageField(msg, field, json, ctx);
             break;
         case "list":
-            readListField(msg.get(field), json, opts);
+            readListField(msg.get(field), json, ctx);
             break;
         case "map":
-            readMapField(msg.get(field), json, opts);
+            readMapField(msg.get(field), json, ctx);
             break;
     }
 }
-function readListOrMapItem(field, json, opts) {
+function readListOrMapItem(field, json, ctx) {
     if (field.scalar && json !== null) {
         return scalarFromJson(field, json);
     }
     if (field.message && !isResetSentinelNullValue(field, json)) {
         const msgValue = (0, reflect_js_1.reflect)(field.message);
-        readMessage(msgValue, json, opts);
+        readMessage(msgValue, json, ctx);
         return msgValue;
     }
     if (field.enum && !isResetSentinelNullValue(field, json)) {
-        return readEnum(field.enum, json, opts.ignoreUnknownFields);
+        return readEnum(field.enum, json, ctx.ignoreUnknownFields);
     }
     throw new error_js_1.FieldError(field, `${field.fieldKind === "list" ? "list item" : "map value"} must not be null`);
 }
-function readMapField(map, json, opts) {
+function readMapField(map, json, ctx) {
     if (json === null) {
         return;
     }
@@ -204,15 +224,20 @@ function readMapField(map, json, opts) {
     if (typeof json != "object" || Array.isArray(json)) {
         throw new error_js_1.FieldError(field, "expected object, got " + (0, reflect_check_js_1.formatVal)(json));
     }
+    const seen = new Set();
     for (const [jsonMapKey, jsonMapValue] of Object.entries(json)) {
         const key = mapKeyFromJson(field.mapKey, jsonMapKey);
-        const value = readListOrMapItem(field, jsonMapValue, opts);
+        if (seen.has(key)) {
+            throw new error_js_1.FieldError(field, `duplicate map key "${jsonMapKey}"`);
+        }
+        seen.add(key);
+        const value = readListOrMapItem(field, jsonMapValue, ctx);
         if (value !== tokenIgnoredUnknownEnum) {
             map.set(key, value);
         }
     }
 }
-function readListField(list, json, opts) {
+function readListField(list, json, ctx) {
     if (json === null) {
         return;
     }
@@ -221,27 +246,27 @@ function readListField(list, json, opts) {
         throw new error_js_1.FieldError(field, "expected Array, got " + (0, reflect_check_js_1.formatVal)(json));
     }
     for (const jsonItem of json) {
-        const value = readListOrMapItem(field, jsonItem, opts);
+        const value = readListOrMapItem(field, jsonItem, ctx);
         if (value !== tokenIgnoredUnknownEnum) {
             list.add(value);
         }
     }
 }
-function readMessageField(msg, field, json, opts) {
+function readMessageField(msg, field, json, ctx) {
     if (isResetSentinelNullValue(field, json)) {
         msg.clear(field);
         return;
     }
     const msgValue = msg.isSet(field) ? msg.get(field) : (0, reflect_js_1.reflect)(field.message);
-    readMessage(msgValue, json, opts);
+    readMessage(msgValue, json, ctx);
     msg.set(field, msgValue);
 }
-function readEnumField(msg, field, json, opts) {
+function readEnumField(msg, field, json, ctx) {
     if (isResetSentinelNullValue(field, json)) {
         msg.clear(field);
         return;
     }
-    const enumValue = readEnum(field.enum, json, opts.ignoreUnknownFields);
+    const enumValue = readEnum(field.enum, json, ctx.ignoreUnknownFields);
     if (enumValue !== tokenIgnoredUnknownEnum) {
         msg.set(field, enumValue);
     }
@@ -370,7 +395,8 @@ function scalarFromJson(field, json) {
 }
 /**
  * Try to parse a JSON value to a map key for the reflect API.
- *
+ * Canonicalizes 64-bit integers given as string, so that "01 and "1" are one
+ * key, and duplicates can raise an error.
  * Returns the input if the JSON value cannot be converted.
  */
 function mapKeyFromJson(type, jsonString) {
@@ -389,6 +415,14 @@ function mapKeyFromJson(type, jsonString) {
         case descriptors_js_1.ScalarType.SFIXED32:
         case descriptors_js_1.ScalarType.SINT32:
             return int32FromJson(jsonString);
+        case descriptors_js_1.ScalarType.INT64:
+        case descriptors_js_1.ScalarType.SINT64:
+        case descriptors_js_1.ScalarType.SFIXED64:
+        case descriptors_js_1.ScalarType.UINT64:
+        case descriptors_js_1.ScalarType.FIXED64:
+            return /^-?0+$/.test(jsonString)
+                ? "0"
+                : jsonString.replace(/^(-?)0+(?=\d)/, "$1");
         default:
             return jsonString;
     }
@@ -417,9 +451,14 @@ function int32FromJson(json) {
     }
     return json;
 }
+/**
+ * Parse a JSON string, rejecting duplicate object keys (which JSON.parse would
+ * otherwise silently merge).
+ */
 function parseJsonString(jsonString, typeName) {
+    let json;
     try {
-        return JSON.parse(jsonString);
+        json = JSON.parse(jsonString);
     }
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
@@ -427,14 +466,91 @@ function parseJsonString(jsonString, typeName) {
         // @ts-expect-error we use the ES2022 error CTOR option "cause" for better stack traces
         { cause: e });
     }
+    checkDuplicateKeys(jsonString, typeName);
+    return json;
 }
-function tryWktFromJson(msg, jsonValue, opts) {
+/**
+ * Scan a JSON string for duplicate object member names at any depth, throwing
+ * if any are found. JSON.parse() silently keeps the last of duplicate keys, so
+ * this raw-string scan is the only way to reject them. It must only be called
+ * with a string that JSON.parse() has already accepted, so it can assume the
+ * input is well-formed.
+ */
+function checkDuplicateKeys(jsonString, typeName) {
+    // One Set of seen member names for each open object; arrays push null.
+    const stack = [];
+    // Whether the next string token is an object member name.
+    let expectKey = false;
+    let i = 0;
+    while (i < jsonString.length) {
+        switch (jsonString[i]) {
+            case "{":
+                stack.push(new Set());
+                expectKey = true;
+                i++;
+                break;
+            case "[":
+                stack.push(null);
+                expectKey = false;
+                i++;
+                break;
+            case "}":
+            case "]":
+                stack.pop();
+                expectKey = false;
+                i++;
+                break;
+            case ",":
+                expectKey = stack[stack.length - 1] != null;
+                i++;
+                break;
+            case ":":
+                expectKey = false;
+                i++;
+                break;
+            case '"': {
+                const open = i++;
+                let escaped = false;
+                while (i < jsonString.length) {
+                    if (jsonString[i] == "\\") {
+                        escaped = true;
+                        i += 2; // skip the backslash and the character it escapes
+                        continue;
+                    }
+                    if (jsonString[i] == '"') {
+                        break;
+                    }
+                    i++;
+                }
+                const close = i++;
+                const seen = stack[stack.length - 1];
+                if (expectKey && seen) {
+                    // Decode escapes (rare) so that, for example, a key written with a
+                    // unicode escape collides with the same key written literally.
+                    const name = escaped
+                        ? JSON.parse(jsonString.substring(open, close + 1))
+                        : jsonString.substring(open + 1, close);
+                    if (seen.has(name)) {
+                        throw new Error(`cannot decode message ${typeName} from JSON: duplicate object key "${name}"`);
+                    }
+                    seen.add(name);
+                }
+                expectKey = false;
+                break;
+            }
+            default:
+                i++;
+                break;
+        }
+    }
+}
+function tryWktFromJson(msg, jsonValue, ctx) {
     if (!msg.desc.typeName.startsWith("google.protobuf.")) {
         return false;
     }
     switch (msg.desc.typeName) {
         case "google.protobuf.Any":
-            anyFromJson(msg.message, jsonValue, opts);
+            anyFromJson(msg.message, jsonValue, ctx);
             return true;
         case "google.protobuf.Timestamp":
             timestampFromJson(msg.message, jsonValue);
@@ -446,13 +562,13 @@ function tryWktFromJson(msg, jsonValue, opts) {
             fieldMaskFromJson(msg.message, jsonValue);
             return true;
         case "google.protobuf.Struct":
-            structFromJson(msg.message, jsonValue);
+            structFromJson(msg.message, jsonValue, ctx);
             return true;
         case "google.protobuf.Value":
-            valueFromJson(msg.message, jsonValue);
+            valueFromJson(msg.message, jsonValue, ctx);
             return true;
         case "google.protobuf.ListValue":
-            listValueFromJson(msg.message, jsonValue);
+            listValueFromJson(msg.message, jsonValue, ctx);
             return true;
         default:
             if ((0, index_js_1.isWrapperDesc)(msg.desc)) {
@@ -468,7 +584,7 @@ function tryWktFromJson(msg, jsonValue, opts) {
             return false;
     }
 }
-function anyFromJson(any, json, opts) {
+function anyFromJson(any, json, ctx) {
     var _a;
     if (json === null || Array.isArray(json) || typeof json != "object") {
         throw new Error(`cannot decode message ${any.$typeName} from JSON: expected object but got ${(0, reflect_check_js_1.formatVal)(json)}`);
@@ -486,21 +602,21 @@ function anyFromJson(any, json, opts) {
     if (!typeName.length) {
         throw new Error(`cannot decode message ${any.$typeName} from JSON: "@type" is invalid`);
     }
-    const desc = (_a = opts.registry) === null || _a === void 0 ? void 0 : _a.getMessage(typeName);
+    const desc = (_a = ctx.registry) === null || _a === void 0 ? void 0 : _a.getMessage(typeName);
     if (!desc) {
         throw new Error(`cannot decode message ${any.$typeName} from JSON: ${typeUrl} is not in the type registry`);
     }
     const msg = (0, reflect_js_1.reflect)(desc);
-    if (typeName.startsWith("google.protobuf.") &&
+    if ((0, index_js_1.hasCustomJsonRepresentation)(desc) &&
         Object.prototype.hasOwnProperty.call(json, "value")) {
         const value = json.value;
-        readMessage(msg, value, opts);
+        readMessage(msg, value, ctx);
     }
     else {
         const copy = Object.assign({}, json);
         // biome-ignore lint/performance/noDelete: <explanation>
         delete copy["@type"];
-        readMessage(msg, copy, opts);
+        readMessage(msg, copy, ctx);
     }
     (0, index_js_1.anyPack)(msg.desc, msg.message, any);
 }
@@ -566,17 +682,20 @@ function fieldMaskFromJson(fieldMask, json) {
         return (0, names_js_1.protoSnakeCase)(path);
     });
 }
-function structFromJson(struct, json) {
+function structFromJson(struct, json, ctx) {
     if (typeof json != "object" || json == null || Array.isArray(json)) {
         throw new Error(`cannot decode message ${struct.$typeName} from JSON ${(0, reflect_check_js_1.formatVal)(json)}`);
     }
     for (const [k, v] of Object.entries(json)) {
         const parsedV = (0, create_js_1.create)(index_js_1.ValueSchema);
-        valueFromJson(parsedV, v);
+        valueFromJson(parsedV, v, ctx);
         struct.fields[k] = parsedV;
     }
 }
-function valueFromJson(value, json) {
+function valueFromJson(value, json, ctx) {
+    if (++ctx.depth > ctx.recursionLimit) {
+        throw new Error(`cannot decode ${value.$typeName} from JSON: maximum recursion depth of ${ctx.recursionLimit} reached`);
+    }
     switch (typeof json) {
         case "number":
             value.kind = { case: "numberValue", value: json };
@@ -593,27 +712,28 @@ function valueFromJson(value, json) {
             }
             else if (Array.isArray(json)) {
                 const listValue = (0, create_js_1.create)(index_js_1.ListValueSchema);
-                listValueFromJson(listValue, json);
+                listValueFromJson(listValue, json, ctx);
                 value.kind = { case: "listValue", value: listValue };
             }
             else {
                 const struct = (0, create_js_1.create)(index_js_1.StructSchema);
-                structFromJson(struct, json);
+                structFromJson(struct, json, ctx);
                 value.kind = { case: "structValue", value: struct };
             }
             break;
         default:
             throw new Error(`cannot decode message ${value.$typeName} from JSON ${(0, reflect_check_js_1.formatVal)(json)}`);
     }
+    ctx.depth--;
     return value;
 }
-function listValueFromJson(listValue, json) {
+function listValueFromJson(listValue, json, ctx) {
     if (!Array.isArray(json)) {
         throw new Error(`cannot decode message ${listValue.$typeName} from JSON ${(0, reflect_check_js_1.formatVal)(json)}`);
     }
     for (const e of json) {
         const value = (0, create_js_1.create)(index_js_1.ValueSchema);
-        valueFromJson(value, e);
+        valueFromJson(value, e, ctx);
         listValue.values.push(value);
     }
 }

package/dist/commonjs/json-value.js

@@ -0,0 +1,15 @@
+"use strict";
+// Copyright 2021-2026 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 });

package/dist/commonjs/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "commonjs",
+  "sideEffects": false
+}

package/dist/{cjs → commonjs}/proto-int64.js

@@ -28,6 +28,7 @@ function makeInt64Support() {
         typeof dv.setBigInt64 === "function" &&
         typeof dv.setBigUint64 === "function" &&
         (!!globalThis.Deno ||
+            !!globalThis.Bun ||
             typeof process != "object" ||
             typeof process.env != "object" ||
             process.env.BUF_BIGINT_DISABLE !== "1");

package/dist/{cjs → commonjs}/reflect/path.d.ts

@@ -89,7 +89,7 @@ export declare function buildPath(schema: DescMessage): PathBuilder;
  * paths that refer to an extension.
  */
 export declare function parsePath(schema: DescMessage, path: string, options?: {
-    registry?: Registry;
+    registry?: Registry | undefined;
 }): Path;
 /**
  * Stringify a path.

package/dist/{cjs → commonjs}/reflect/reflect-check.js

@@ -80,7 +80,9 @@ function checkSingular(field, value) {
     }
     if (field.enum !== undefined) {
         if (field.enum.open) {
-            return Number.isInteger(value);
+            // Open enums accept unrecognized values, but enum values are always
+            // int32 (see https://protobuf.dev/programming-guides/proto3/#enum).
+            return checkScalarValue(value, descriptors_js_1.ScalarType.INT32);
         }
         return field.enum.values.some((v) => v.number === value);
     }

package/dist/commonjs/reflect/scalar.d.ts

@@ -0,0 +1,43 @@
+import { ScalarType } from "../descriptors.js";
+/**
+ * ScalarValue maps from a scalar field type to a TypeScript value type.
+ */
+export type ScalarValue<T = ScalarType, LongAsString extends boolean = false> = T extends ScalarType.STRING ? string : T extends ScalarType.INT32 ? 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 ? LongAsString extends true ? string : bigint : T extends ScalarType.SINT64 ? LongAsString extends true ? string : bigint : T extends ScalarType.SFIXED64 ? LongAsString extends true ? string : bigint : T extends ScalarType.UINT64 ? LongAsString extends true ? string : bigint : T extends ScalarType.FIXED64 ? LongAsString extends true ? string : bigint : T extends ScalarType.BOOL ? boolean : T extends ScalarType.BYTES ? Uint8Array : never;
+/**
+ * Returns true if both scalar values are equal.
+ *
+ * For float and double, values are compared following IEEE semantics: -0
+ * equals 0, and NaN does not equal NaN. This is value equality, not identity.
+ *
+ * It deliberately differs from isScalarZeroValue, which treats -0 as distinct
+ * from 0. A value can equal the zero value without being a zero value
+ * (scalarEquals(DOUBLE, -0, 0) is true while isScalarZeroValue(DOUBLE, -0) is
+ * false) so this function must not be used to derive implicit presence.
+ */
+export declare function scalarEquals(type: ScalarType, a: ScalarValue | undefined, b: ScalarValue | undefined): boolean;
+/**
+ * Returns the zero value for the given scalar type, the value a field of this
+ * type has when unset: 0 for numeric types, "" for strings, false for
+ * booleans, and an empty Uint8Array for bytes. For 64-bit integer types, the
+ * result is "0" when longAsString is true, otherwise 0n.
+ *
+ * This is the type's zero value, not a proto2 custom field default. For float
+ * and double it is +0; isScalarZeroValue treats only +0, not -0, as this value.
+ */
+export declare function scalarZeroValue<T extends ScalarType, LongAsString extends boolean>(type: T, longAsString: LongAsString): ScalarValue<T, LongAsString>;
+/**
+ * Returns true if the value is the zero value for the given scalar type: `0`
+ * for numeric types, `false` for booleans, `""` for strings, and an empty
+ * Uint8Array for bytes.
+ *
+ * This is the implicit-presence default check. A singular field with implicit
+ * presence is treated as unset, and omitted from the wire, when its value is
+ * the zero value. With explicit presence, or in repeated and map fields,
+ * presence is structural and this function does not apply.
+ *
+ * Note that -0 is NOT a zero value for float and double: under implicit
+ * presence, +0 is omitted from the wire but -0 is written, following the
+ * proto3 specification. As a result this can disagree with scalarEquals, which
+ * compares by value and treats -0 as equal to 0.
+ */
+export declare function isScalarZeroValue(type: ScalarType, value: unknown): boolean;

package/dist/{cjs → commonjs}/reflect/scalar.js

@@ -20,6 +20,14 @@ const proto_int64_js_1 = require("../proto-int64.js");
 const descriptors_js_1 = require("../descriptors.js");
 /**
  * Returns true if both scalar values are equal.
+ *
+ * For float and double, values are compared following IEEE semantics: -0
+ * equals 0, and NaN does not equal NaN. This is value equality, not identity.
+ *
+ * It deliberately differs from isScalarZeroValue, which treats -0 as distinct
+ * from 0. A value can equal the zero value without being a zero value
+ * (scalarEquals(DOUBLE, -0, 0) is true while isScalarZeroValue(DOUBLE, -0) is
+ * false) so this function must not be used to derive implicit presence.
  */
 function scalarEquals(type, a, b) {
     if (a === b) {
@@ -56,7 +64,13 @@ function scalarEquals(type, a, b) {
     return false;
 }
 /**
- * Returns the zero value for the given scalar type.
+ * Returns the zero value for the given scalar type, the value a field of this
+ * type has when unset: 0 for numeric types, "" for strings, false for
+ * booleans, and an empty Uint8Array for bytes. For 64-bit integer types, the
+ * result is "0" when longAsString is true, otherwise 0n.
+ *
+ * This is the type's zero value, not a proto2 custom field default. For float
+ * and double it is +0; isScalarZeroValue treats only +0, not -0, as this value.
  */
 function scalarZeroValue(type, longAsString) {
     switch (type) {
@@ -82,11 +96,19 @@ function scalarZeroValue(type, longAsString) {
     }
 }
 /**
- * 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.
+ * Returns true if the value is the zero value for the given scalar type: `0`
+ * for numeric types, `false` for booleans, `""` for strings, and an empty
+ * Uint8Array for bytes.
  *
- * In proto3, zero-values are not written to the wire, unless the field is
- * optional or repeated.
+ * This is the implicit-presence default check. A singular field with implicit
+ * presence is treated as unset, and omitted from the wire, when its value is
+ * the zero value. With explicit presence, or in repeated and map fields,
+ * presence is structural and this function does not apply.
+ *
+ * Note that -0 is NOT a zero value for float and double: under implicit
+ * presence, +0 is omitted from the wire but -0 is written, following the
+ * proto3 specification. As a result this can disagree with scalarEquals, which
+ * compares by value and treats -0 as equal to 0.
  */
 function isScalarZeroValue(type, value) {
     switch (type) {
@@ -96,7 +118,12 @@ function isScalarZeroValue(type, value) {
             return value === "";
         case descriptors_js_1.ScalarType.BYTES:
             return value instanceof Uint8Array && !value.byteLength;
+        case descriptors_js_1.ScalarType.DOUBLE:
+        case descriptors_js_1.ScalarType.FLOAT:
+            // Object.is distinguishes -0 from 0.
+            return Object.is(value, 0);
         default:
-            return value == 0; // Loose comparison matches 0n, 0 and "0"
+            // Loose comparison matches 0n, 0 and "0".
+            return value == 0;
     }
 }