@bufbuild/protobuf 1.9.0 → 2.0.0-alpha.2

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

@@ -0,0 +1,143 @@
+// 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.
+import { ScalarType, scalarTypeDescription } from "./scalar.js";
+import { checkScalarValue } from "./scalar.js";
+import { isMessage } from "../is-message.js";
+import { FieldError } from "./error.js";
+import { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";
+export function checkField(field, value) {
+    const check = field.fieldKind == "list"
+        ? isReflectList(value, field)
+        : field.fieldKind == "map"
+            ? 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 FieldError(field, reason);
+}
+export function checkListItem(field, index, value) {
+    const check = checkSingular(field, value);
+    if (check !== true) {
+        return new FieldError(field, `list item #${index + 1}: ${reasonSingular(field, value, check)}`);
+    }
+    return undefined;
+}
+export function checkMapEntry(field, key, value) {
+    const checkKey = checkScalarValue(key, field.mapKey);
+    if (checkKey !== true) {
+        return new FieldError(field, `invalid map key: ${reasonSingular({ scalar: field.mapKey }, key, checkKey)}`);
+    }
+    const checkVal = checkSingular(field, value);
+    if (checkVal !== true) {
+        return new FieldError(field, `map entry ${formatVal(key)}: ${reasonSingular(field, value, checkVal)}`);
+    }
+    return undefined;
+}
+function checkSingular(field, value) {
+    if (field.scalar !== undefined) {
+        return 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 isReflectMessage(value, field.message);
+}
+function reasonSingular(field, val, details) {
+    details =
+        typeof details == "string" ? `: ${details}` : `, got ${formatVal(val)}`;
+    if (field.scalar !== undefined) {
+        return `expected ${scalarTypeDescription(field.scalar)}` + details;
+    }
+    else if (field.enum !== undefined) {
+        return `expected ${field.enum.toString()}` + details;
+    }
+    return `expected ${formatReflectMessage(field.message)}` + details;
+}
+export 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 (isReflectList(val)) {
+                return formatReflectList(val.field());
+            }
+            if (isReflectMap(val)) {
+                return formatReflectMap(val.field());
+            }
+            if (isReflectMessage(val)) {
+                return formatReflectMessage(val.desc);
+            }
+            if (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;
+    }
+}
+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 (${ScalarType[field.scalar]})`;
+    }
+}
+function formatReflectMap(field) {
+    switch (field.mapKind) {
+        case "message":
+            return `ReflectMap (${ScalarType[field.mapKey]}, ${field.message.toString()})`;
+        case "enum":
+            return `ReflectMap (${ScalarType[field.mapKey]}, ${field.enum.toString()})`;
+        case "scalar":
+            return `ReflectMap (${ScalarType[field.mapKey]}, ${ScalarType[field.scalar]})`;
+    }
+}

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

@@ -0,0 +1,284 @@
+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";
+/**
+ * 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: ReflectAddListItemValue<Field>): FieldError | undefined;
+    /**
+     * Set a map entry.
+     */
+    setMapEntry<Field extends DescField & {
+        fieldKind: "map";
+    }>(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";
+    };
+    /**
+     * 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[];
+}
+/**
+ * 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";
+    };
+    /**
+     * 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>;
+}
+/**
+ * A ReflectMap key.
+ */
+export type MapEntryKey = string | number | bigint | boolean;
+type enumVal = number;
+/**
+ * The return type of ReflectMessage.get()
+ */
+export 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 : Field extends {
+    fieldKind: "message";
+} ? ReflectMessage : Field extends {
+    fieldKind: "scalar";
+    scalar: infer T;
+} ? 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 : Field extends {
+    fieldKind: "message";
+} ? ReflectMessage : Field extends {
+    fieldKind: "scalar";
+    scalar: infer T;
+} ? ScalarValue<T> : never);
+/**
+ * The type of the "value" argument of ReflectMessage.addListItem()
+ */
+export type ReflectAddListItemValue<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);
+/**
+ * The type of the "value" argument of ReflectMessage.setMapEntry()
+ */
+export type ReflectSetMapEntryValue<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/esm/reflect/reflect-types.js

@@ -0,0 +1,15 @@
+// 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.
+import { FieldError } from "./error.js";
+import { unsafeLocal } from "./unsafe.js";

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

@@ -0,0 +1,32 @@
+import type { DescField, DescMessage } from "../desc-types.js";
+import type { MessageShape } from "../types.js";
+import type { MapEntryKey, ReflectList, ReflectMap, ReflectMessage } from "./reflect-types.js";
+/**
+ * Create a ReflectMessage.
+ */
+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;
+/**
+ * Create a ReflectList.
+ */
+export declare function reflectList<V>(field: DescField & {
+    fieldKind: "list";
+}, unsafeInput?: unknown[], check?: boolean): ReflectList<V>;
+/**
+ * Create a ReflectMap.
+ */
+export declare function reflectMap<K extends MapEntryKey, V>(field: DescField & {
+    fieldKind: "map";
+}, unsafeInput?: Record<string, unknown>, check?: boolean): ReflectMap<K, V>;