@bufbuild/protobuf 1.8.0 → 2.0.0-alpha.1

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

@@ -0,0 +1,150 @@
+"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.formatVal = exports.checkMapEntry = exports.checkListItem = exports.checkField = void 0;
+const scalar_js_1 = require("./scalar.js");
+const scalar_js_2 = require("./scalar.js");
+const is_message_js_1 = require("../is-message.js");
+const error_js_1 = require("./error.js");
+const guard_js_1 = require("./guard.js");
+function checkField(field, value) {
+    const check = field.fieldKind == "list"
+        ? (0, guard_js_1.isReflectList)(value, field)
+        : field.fieldKind == "map"
+            ? (0, guard_js_1.isReflectMap)(value, field)
+            : checkSingular(field, value);
+    if (check === true) {
+        return undefined;
+    }
+    let reason;
+    switch (field.fieldKind) {
+        case "list":
+            reason = `expected ${formatReflectList(field)}, got ${formatVal(value)}`;
+            break;
+        case "map":
+            reason = `expected ${formatReflectMap(field)}, got ${formatVal(value)}`;
+            break;
+        default: {
+            reason = reasonSingular(field, value, check);
+        }
+    }
+    return new error_js_1.FieldError(field, reason);
+}
+exports.checkField = checkField;
+function checkListItem(field, index, value) {
+    const check = checkSingular(field, value);
+    if (check !== true) {
+        return new error_js_1.FieldError(field, `list item #${index + 1}: ${reasonSingular(field, value, check)}`);
+    }
+    return undefined;
+}
+exports.checkListItem = checkListItem;
+function checkMapEntry(field, key, value) {
+    const checkKey = (0, scalar_js_2.checkScalarValue)(key, field.mapKey);
+    if (checkKey !== true) {
+        return new error_js_1.FieldError(field, `invalid map key: ${reasonSingular({ scalar: field.mapKey }, key, checkKey)}`);
+    }
+    const checkVal = checkSingular(field, value);
+    if (checkVal !== true) {
+        return new error_js_1.FieldError(field, `map entry ${formatVal(key)}: ${reasonSingular(field, value, checkVal)}`);
+    }
+    return undefined;
+}
+exports.checkMapEntry = checkMapEntry;
+function checkSingular(field, value) {
+    if (field.scalar !== undefined) {
+        return (0, scalar_js_2.checkScalarValue)(value, field.scalar);
+    }
+    if (field.enum !== undefined) {
+        if (field.enum.open) {
+            return Number.isInteger(value);
+        }
+        return field.enum.values.some((v) => v.number === value);
+    }
+    return (0, guard_js_1.isReflectMessage)(value, field.message);
+}
+function reasonSingular(field, val, details) {
+    details =
+        typeof details == "string" ? `: ${details}` : `, got ${formatVal(val)}`;
+    if (field.scalar !== undefined) {
+        return `expected ${(0, scalar_js_1.scalarTypeDescription)(field.scalar)}` + details;
+    }
+    else if (field.enum !== undefined) {
+        return `expected ${field.enum.toString()}` + details;
+    }
+    return `expected ${formatReflectMessage(field.message)}` + details;
+}
+function formatVal(val) {
+    switch (typeof val) {
+        case "object":
+            if (val === null) {
+                return "null";
+            }
+            if (val instanceof Uint8Array) {
+                return `Uint8Array(${val.length})`;
+            }
+            if (Array.isArray(val)) {
+                return `Array(${val.length})`;
+            }
+            if ((0, guard_js_1.isReflectList)(val)) {
+                return formatReflectList(val.field());
+            }
+            if ((0, guard_js_1.isReflectMap)(val)) {
+                return formatReflectMap(val.field());
+            }
+            if ((0, guard_js_1.isReflectMessage)(val)) {
+                return formatReflectMessage(val.desc);
+            }
+            if ((0, is_message_js_1.isMessage)(val)) {
+                return `message ${val.$typeName}`;
+            }
+            return "object";
+        case "string":
+            return val.length > 30 ? "string" : `"${val.split('"').join('\\"')}"`;
+        case "boolean":
+            return String(val);
+        case "number":
+            return String(val);
+        case "bigint":
+            return String(val) + "n";
+        default:
+            // "symbol" | "undefined" | "object" | "function"
+            return typeof val;
+    }
+}
+exports.formatVal = formatVal;
+function formatReflectMessage(desc) {
+    return `ReflectMessage (${desc.typeName})`;
+}
+function formatReflectList(field) {
+    switch (field.listKind) {
+        case "message":
+            return `ReflectList (${field.message.toString()})`;
+        case "enum":
+            return `ReflectList (${field.enum.toString()})`;
+        case "scalar":
+            return `ReflectList (${scalar_js_1.ScalarType[field.scalar]})`;
+    }
+}
+function formatReflectMap(field) {
+    switch (field.mapKind) {
+        case "message":
+            return `ReflectMap (${scalar_js_1.ScalarType[field.mapKey]}, ${field.message.toString()})`;
+        case "enum":
+            return `ReflectMap (${scalar_js_1.ScalarType[field.mapKey]}, ${field.enum.toString()})`;
+        case "scalar":
+            return `ReflectMap (${scalar_js_1.ScalarType[field.mapKey]}, ${scalar_js_1.ScalarType[field.scalar]})`;
+    }
+}

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

@@ -0,0 +1,136 @@
+import type { DescField, DescMessage, DescOneof } from "../desc-types.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";
+export interface ReflectMessage {
+    readonly message: Message;
+    readonly desc: DescMessage;
+    readonly fields: readonly DescField[];
+    readonly sortedFields: readonly DescField[];
+    readonly oneofs: readonly DescOneof[];
+    readonly members: readonly (DescField | DescOneof)[];
+    findNumber(number: number): DescField | undefined;
+    isSet(field: DescField): boolean;
+    clear(field: DescField): void;
+    oneofCase(oneof: DescOneof): DescField | undefined;
+    get<Field extends DescField>(field: Field): ReflectGetValue<Field>;
+    set<Field extends DescField>(field: Field, value: ReflectSetValue<Field>): FieldError | undefined;
+    addListItem<Field extends DescField & {
+        fieldKind: "list";
+    }>(field: Field, value: NewListItem<Field>): FieldError | undefined;
+    setMapEntry<Field extends DescField & {
+        fieldKind: "map";
+    }>(field: Field, key: MapEntryKey, value: NewMapEntryValue<Field>): FieldError | undefined;
+    getUnknown(): UnknownField[] | undefined;
+    setUnknown(value: UnknownField[]): void;
+    [unsafeLocal]: Message;
+}
+export interface ReflectList<V = unknown> extends Iterable<V> {
+    field(): DescField & {
+        fieldKind: "list";
+    };
+    /**
+     * The size of the list.
+     */
+    readonly size: number;
+    /**
+     * Retrieves the item at the specified index, or undefined if the index
+     * is out of range.
+     */
+    get(index: number): V | undefined;
+    /**
+     * Adds an item - or several items - at the end of the list.
+     * Returns an error if an item is invalid for this list.
+     */
+    add(...item: V[]): FieldError | undefined;
+    /**
+     * Replaces the item at the specified index with the specified item.
+     * Returns an error if the index is out of range (index < 0 || index >= size).
+     * Returns an error if the item is invalid for this list.
+     */
+    set(index: number, item: V): FieldError | undefined;
+    /**
+     * Removes all items from the list.
+     */
+    clear(): void;
+    [Symbol.iterator](): IterableIterator<V>;
+    entries(): IterableIterator<[number, V]>;
+    keys(): IterableIterator<number>;
+    values(): IterableIterator<V>;
+    [unsafeLocal]: unknown[];
+}
+export interface ReflectMap<K extends MapEntryKey = MapEntryKey, V = unknown> extends ReadonlyMap<K, V> {
+    field(): DescField & {
+        fieldKind: "map";
+    };
+    /**
+     * Removes the entry for the specified key.
+     * Returns false if the key is unknown.
+     */
+    delete(key: K): boolean;
+    /**
+     * Sets or replaces the item at the specified key with the specified value.
+     * Returns an error if the key or value is invalid for this map.
+     */
+    set(key: K, value: V): FieldError | undefined;
+    /**
+     * Removes all entries from the map.
+     */
+    clear(): void;
+    [unsafeLocal]: Record<string, unknown>;
+}
+export type MapEntryKey = string | number | bigint | boolean;
+type enumVal = number;
+type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
+    fieldKind: "map";
+} ? (Field extends {
+    mapKind: "message";
+} ? ReflectMap<MapEntryKey, ReflectMessage> : Field extends {
+    mapKind: "enum";
+} ? ReflectMap<MapEntryKey, enumVal> : Field extends {
+    mapKind: "scalar";
+    scalar: infer T;
+} ? ReflectMap<MapEntryKey, ScalarValue<T, LongType.BIGINT>> : never) : Field extends {
+    fieldKind: "list";
+} ? ReflectList : Field extends {
+    fieldKind: "enum";
+} ? number | undefined : Field extends {
+    fieldKind: "message";
+} ? ReflectMessage : Field extends {
+    fieldKind: "scalar";
+    scalar: infer T;
+} ? ScalarValue<T> | undefined : never);
+type ReflectSetValue<Field extends DescField = DescField> = (Field extends {
+    fieldKind: "map";
+} ? ReflectMap : Field extends {
+    fieldKind: "list";
+} ? ReflectList : Field extends {
+    fieldKind: "enum";
+} ? number | undefined : Field extends {
+    fieldKind: "message";
+} ? ReflectMessage : Field extends {
+    fieldKind: "scalar";
+    scalar: infer T;
+} ? ScalarValue<T> | undefined : never);
+type NewListItem<Field extends DescField & {
+    fieldKind: "list";
+}> = (Field extends {
+    listKind: "scalar";
+    scalar: infer T;
+} ? ScalarValue<T> : Field extends {
+    listKind: "enum";
+} ? enumVal : Field extends {
+    listKind: "message";
+} ? ReflectMessage : never);
+type NewMapEntryValue<Field extends DescField & {
+    fieldKind: "map";
+}> = (Field extends {
+    mapKind: "enum";
+} ? enumVal : Field extends {
+    mapKind: "message";
+} ? ReflectMessage : Field extends {
+    mapKind: "scalar";
+    scalar: infer T;
+} ? ScalarValue<T, LongType.BIGINT> : never);
+export {};

package/dist/cjs/{extension.js → reflect/reflect-types.js}

@@ -13,3 +13,4 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
+const unsafe_js_1 = require("./unsafe.js");

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

@@ -0,0 +1,23 @@
+import type { DescField, DescMessage } from "../desc-types.js";
+import type { MessageShape } from "../types.js";
+import type { MapEntryKey, ReflectList, ReflectMap, ReflectMessage } from "./reflect-types.js";
+export declare function reflect<Desc extends DescMessage>(messageDesc: Desc, message?: MessageShape<Desc>, opt?: {
+    /**
+     * By default, field values are validated when setting them. For example,
+     * a value for an uint32 field must be a ECMAScript Number >= 0.
+     *
+     * Note that setting a message field validates the type of the message,
+     * but does not check its fields.
+     *
+     * In some contexts, field values are trusted, and performance can be
+     * improved by disabling validation by setting disableFieldValueCheck to
+     * `false`.
+     */
+    disableFieldValueCheck?: boolean;
+}): ReflectMessage;
+export declare function reflectList<V>(field: DescField & {
+    fieldKind: "list";
+}, unsafeInput?: unknown[]): ReflectList<V>;
+export declare function reflectMap<K extends MapEntryKey, V>(field: DescField & {
+    fieldKind: "map";
+}, unsafeInput?: Record<string, unknown>): ReflectMap<K, V>;