@bufbuild/protobuf 1.8.0 → 2.0.0-alpha.1

package/dist/esm/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/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,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>;

package/dist/esm/reflect/reflect.js

@@ -0,0 +1,403 @@
+// 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 { checkField, checkListItem, checkMapEntry } from "./reflect-check.js";
+import { FieldError } from "./error.js";
+import { unsafeAddListItem, unsafeClear, unsafeGet, unsafeIsSet, unsafeLocal, unsafeOneofCase, unsafeSet, unsafeSetMapEntry, } from "./unsafe.js";
+import { create } from "../create.js";
+import { isWrapper, isWrapperDesc } from "../wkt/wrappers.js";
+import { LongType, ScalarType } from "./scalar.js";
+import { protoInt64 } from "../proto-int64.js";
+import { isReflectList, isReflectMap, isReflectMessage } from "./guard.js";
+export function reflect(messageDesc, message, 
+// TODO either remove this option, or support it in reflect-list and reflect-map as well
+opt) {
+    message !== null && message !== void 0 ? message : (message = create(messageDesc));
+    const check = (opt === null || opt === void 0 ? void 0 : opt.disableFieldValueCheck) !== true;
+    let fieldsByNumber;
+    let sortedFields;
+    return {
+        message,
+        [unsafeLocal]: message,
+        desc: messageDesc,
+        fields: messageDesc.fields,
+        oneofs: messageDesc.oneofs,
+        members: messageDesc.members,
+        get sortedFields() {
+            return (sortedFields !== null && sortedFields !== void 0 ? sortedFields : (sortedFields = messageDesc.fields
+                .concat()
+                .sort((a, b) => a.number - b.number)));
+        },
+        findNumber(number) {
+            if (!fieldsByNumber) {
+                fieldsByNumber = new Map(messageDesc.fields.map((f) => [f.number, f]));
+            }
+            return fieldsByNumber.get(number);
+        },
+        oneofCase(oneof) {
+            assertOwn(message, oneof);
+            return unsafeOneofCase(message, oneof);
+        },
+        isSet(field) {
+            assertOwn(message, field);
+            return unsafeIsSet(message, field);
+        },
+        clear(field) {
+            assertOwn(message, field);
+            unsafeClear(message, field);
+        },
+        get(field) {
+            assertOwn(message, field);
+            let value = unsafeGet(message, field);
+            switch (field.fieldKind) {
+                case "list":
+                    return reflectList(field, value);
+                case "map":
+                    // TODO fix types
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+                    return reflectMap(field, value); // eslint-disable-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return
+                case "message":
+                    if (value !== undefined &&
+                        !field.oneof &&
+                        isWrapperDesc(field.message)) {
+                        value = {
+                            $typeName: field.message.typeName,
+                            value: longToReflect(field.message.fields[0], value),
+                        };
+                    }
+                    return reflect(field.message, value);
+                case "scalar":
+                    return longToReflect(field, value);
+                case "enum":
+                    return value;
+            }
+        },
+        set(field, value) {
+            assertOwn(message, field);
+            if (check) {
+                const err = checkField(field, value);
+                if (err) {
+                    return err;
+                }
+            }
+            let local = value;
+            if (isReflectMap(value) || isReflectList(value)) {
+                local = value[unsafeLocal];
+            }
+            else if (isReflectMessage(value)) {
+                const msg = value.message;
+                local = !field.oneof && isWrapper(msg) ? msg.value : msg;
+            }
+            else {
+                local = longToLocal(field, value);
+            }
+            unsafeSet(message, field, local);
+            return undefined;
+        },
+        addListItem(field, value) {
+            assertOwn(message, field);
+            assertKind(field, "list");
+            if (check) {
+                if (checkListItem(field, 0, value)) {
+                    const arr = unsafeGet(message, field);
+                    return checkListItem(field, arr.length, value);
+                }
+            }
+            unsafeAddListItem(message, field, listItemToLocal(field, value));
+            return undefined;
+        },
+        setMapEntry(field, key, value) {
+            assertOwn(message, field);
+            assertKind(field, "map");
+            if (check) {
+                const err = checkMapEntry(field, key, value);
+                if (err) {
+                    return err;
+                }
+            }
+            unsafeSetMapEntry(message, field, mapKeyToLocal(key), mapValueToLocal(field, value));
+            return undefined;
+        },
+        getUnknown() {
+            return message.$unknown;
+        },
+        setUnknown(value) {
+            message.$unknown = value;
+        },
+    };
+}
+function assertKind(field, kind) {
+    if (field.fieldKind != kind) {
+        throw new FieldError(field, `${field.toString()} is ${field.fieldKind}`, "ForeignFieldError");
+    }
+}
+function assertOwn(owner, member) {
+    if (member.parent.typeName !== owner.$typeName) {
+        throw new FieldError(member, `cannot use ${member.toString()} with message ${owner.$typeName}`, "ForeignFieldError");
+    }
+}
+export function reflectList(field, unsafeInput) {
+    const arr = unsafeInput !== null && unsafeInput !== void 0 ? unsafeInput : [];
+    return {
+        [unsafeLocal]: arr,
+        field() {
+            return field;
+        },
+        get size() {
+            return arr.length;
+        },
+        get(index) {
+            const item = arr[index];
+            return item === undefined
+                ? undefined
+                : listItemToReflect(field, item);
+        },
+        set(index, item) {
+            if (index < 0 || index >= arr.length) {
+                return new FieldError(field, `list item #${index + 1}: out of range`);
+            }
+            const err = checkListItem(field, index, item);
+            if (!err) {
+                arr[index] = listItemToLocal(field, item);
+            }
+            return err;
+        },
+        add(...items) {
+            let err;
+            for (let i = 0; i < items.length && !err; i++) {
+                err = checkListItem(field, arr.length + i, items[i]);
+            }
+            if (!err) {
+                for (const item of items) {
+                    arr.push(listItemToLocal(field, item));
+                }
+            }
+            return err;
+        },
+        clear() {
+            arr.splice(0, arr.length);
+        },
+        [Symbol.iterator]() {
+            return this.values();
+        },
+        keys() {
+            return arr.keys();
+        },
+        *values() {
+            for (const item of arr) {
+                yield listItemToReflect(field, item);
+            }
+        },
+        *entries() {
+            for (let i = 0; i < arr.length; i++) {
+                yield [i, listItemToReflect(field, arr[i])];
+            }
+        },
+    };
+}
+export function reflectMap(field, unsafeInput) {
+    const obj = unsafeInput !== null && unsafeInput !== void 0 ? unsafeInput : {};
+    return {
+        [unsafeLocal]: obj,
+        field() {
+            return field;
+        },
+        set(key, value) {
+            const err = checkMapEntry(field, key, value);
+            if (!err) {
+                obj[mapKeyToLocal(key)] = mapValueToLocal(field, value);
+            }
+            return err;
+        },
+        delete(key) {
+            const k = mapKeyToLocal(key);
+            const has = Object.prototype.hasOwnProperty.call(obj, k);
+            if (has) {
+                delete obj[k];
+            }
+            return has;
+        },
+        clear() {
+            for (const key of Object.keys(obj)) {
+                delete obj[key];
+            }
+        },
+        get(key) {
+            let val = obj[mapKeyToLocal(key)];
+            if (val !== undefined) {
+                val = mapValueToReflect(field, val);
+            }
+            return val;
+        },
+        has(key) {
+            return Object.prototype.hasOwnProperty.call(obj, mapKeyToLocal(key));
+        },
+        *keys() {
+            for (const objKey of Object.keys(obj)) {
+                yield mapKeyToReflect(objKey, field.mapKey);
+            }
+        },
+        *entries() {
+            for (const objEntry of Object.entries(obj)) {
+                yield [
+                    mapKeyToReflect(objEntry[0], field.mapKey),
+                    mapValueToReflect(field, objEntry[1]),
+                ];
+            }
+        },
+        [Symbol.iterator]() {
+            return this.entries();
+        },
+        get size() {
+            return Object.keys(obj).length;
+        },
+        *values() {
+            for (const val of Object.values(obj)) {
+                yield mapValueToReflect(field, val);
+            }
+        },
+        forEach(callbackfn, thisArg) {
+            for (const mapEntry of this.entries()) {
+                callbackfn.call(thisArg, mapEntry[1], mapEntry[0], this);
+            }
+        },
+    };
+}
+function listItemToLocal(field, value) {
+    if (isReflectMessage(value)) {
+        return value.message;
+    }
+    return longToLocal(field, value);
+}
+function listItemToReflect(field, value) {
+    if (field.listKind == "message") {
+        return reflect(field.message, value);
+    }
+    return longToReflect(field, value);
+}
+function mapValueToLocal(field, value) {
+    if (isReflectMessage(value)) {
+        return value.message;
+    }
+    return longToLocal(field, value);
+}
+function mapValueToReflect(field, value) {
+    if (field.mapKind == "message") {
+        return reflect(field.message, value);
+    }
+    return value;
+}
+function mapKeyToLocal(key) {
+    return typeof key == "string" || typeof key == "number" ? key : String(key);
+}
+/**
+ * Converts a map key (any scalar value except float, double, or bytes) from its
+ * representation in a message (string or number, the only possible object key
+ * types) to the closest possible type in ECMAScript.
+ */
+function mapKeyToReflect(key, type) {
+    switch (type) {
+        case ScalarType.STRING:
+            return key;
+        case ScalarType.INT32:
+        case ScalarType.FIXED32:
+        case ScalarType.UINT32:
+        case ScalarType.SFIXED32:
+        case ScalarType.SINT32: {
+            const n = Number.parseInt(key);
+            if (Number.isFinite(n)) {
+                return n;
+            }
+            break;
+        }
+        case ScalarType.BOOL:
+            switch (key) {
+                case "true":
+                    return true;
+                case "false":
+                    return false;
+            }
+            break;
+        case ScalarType.UINT64:
+        case ScalarType.FIXED64:
+            try {
+                return protoInt64.uParse(key);
+            }
+            catch (_a) {
+                //
+            }
+            break;
+        default:
+            // INT64, SFIXED64, SINT64
+            try {
+                return protoInt64.parse(key);
+            }
+            catch (_b) {
+                //
+            }
+            break;
+    }
+    return key;
+}
+function longToReflect(field, value) {
+    if (field.scalar !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+        switch (field.scalar) {
+            case ScalarType.INT64:
+            case ScalarType.SFIXED64:
+            case ScalarType.SINT64:
+                if ("longType" in field &&
+                    field.longType == LongType.STRING &&
+                    typeof value == "string") {
+                    value = protoInt64.parse(value);
+                }
+                break;
+            case ScalarType.FIXED64:
+            case ScalarType.UINT64:
+                if ("longType" in field &&
+                    field.longType == LongType.STRING &&
+                    typeof value == "string") {
+                    value = protoInt64.uParse(value);
+                }
+                break;
+        }
+    }
+    return value;
+}
+function longToLocal(field, value) {
+    if (field.scalar !== undefined) {
+        // eslint-disable-next-line @typescript-eslint/switch-exhaustiveness-check
+        switch (field.scalar) {
+            case ScalarType.INT64:
+            case ScalarType.SFIXED64:
+            case ScalarType.SINT64:
+                if ("longType" in field && field.longType == LongType.STRING) {
+                    value = String(value);
+                }
+                else if (typeof value == "string" || typeof value == "number") {
+                    value = protoInt64.parse(value);
+                }
+                break;
+            case ScalarType.FIXED64:
+            case ScalarType.UINT64:
+                if ("longType" in field && field.longType == LongType.STRING) {
+                    value = String(value);
+                }
+                else if (typeof value == "string" || typeof value == "number") {
+                    value = protoInt64.uParse(value);
+                }
+                break;
+        }
+    }
+    return value;
+}

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

@@ -0,0 +1,82 @@
+import type { FileDescriptorProto, FileDescriptorSet } from "../wkt/gen/google/protobuf/descriptor_pb.js";
+import type { DescEnum, DescExtension, DescFile, DescMessage, DescService, SupportedEdition } from "../desc-types.js";
+/**
+ * A set of descriptors for messages, enumerations, extensions,
+ * and services.
+ */
+export interface Registry {
+    readonly kind: "registry";
+    /**
+     * All types (message, enumeration, extension, or service) contained
+     * in this registry.
+     */
+    [Symbol.iterator](): IterableIterator<DescMessage | DescEnum | DescExtension | DescService>;
+    /**
+     * Look up a type (message, enumeration, extension, or service) by
+     * its fully qualified name.
+     */
+    get(typeName: string): DescMessage | DescEnum | DescExtension | DescService | undefined;
+    /**
+     * Look up a message descriptor by its fully qualified name.
+     */
+    getMessage(typeName: string): DescMessage | undefined;
+    /**
+     * Look up an enumeration descriptor by its fully qualified name.
+     */
+    getEnum(typeName: string): DescEnum | undefined;
+    /**
+     * Look up an extension descriptor by its fully qualified name.
+     */
+    getExtension(typeName: string): DescExtension | undefined;
+    /**
+     * Look up an extension by the extendee - the message it extends - and
+     * the extension number.
+     */
+    getExtensionFor(extendee: DescMessage, no: number): DescExtension | undefined;
+    /**
+     * Look up a service descriptor by its fully qualified name.
+     */
+    getService(typeName: string): DescService | undefined;
+}
+/**
+ * A set of descriptors for messages, enumerations, extensions,
+ * and services - and files.
+ */
+export interface FileRegistry extends Registry {
+    /**
+     * All files in this registry.
+     */
+    readonly files: Iterable<DescFile>;
+    /**
+     * Look up a file descriptor by file name.
+     */
+    getFile(fileName: string): DescFile | undefined;
+}
+/**
+ * Create a registry from the given inputs.
+ *
+ * An input can be:
+ * - Any message, enum, service, or extension descriptor, which adds just the
+ *   descriptor for this type.
+ * - A file descriptor, which adds all typed defined in this file.
+ * - A registry, which adds all types from the registry.
+ *
+ * For duplicate descriptors (same type name), the one given last wins.
+ */
+export declare function createRegistry(...input: (Registry | DescFile | DescMessage | DescEnum | DescExtension | DescService)[]): Registry;
+/**
+ * Create a registry (including file descriptors) from a google.protobuf.FileDescriptorSet
+ * message.
+ */
+export declare function createFileRegistry(fileDescriptorSet: FileDescriptorSet): FileRegistry;
+/**
+ * Create a registry (including file descriptors) from a google.protobuf.FileDescriptorProto
+ * message. For every import, the given resolver function is called.
+ */
+export declare function createFileRegistry(fileDescriptorProto: FileDescriptorProto, resolve: (protoFileName: string) => FileDescriptorProto | DescFile | undefined): FileRegistry;
+/**
+ * Create a registry (including file descriptors) from one or more registries,
+ * merging them.
+ */
+export declare function createFileRegistry(...registries: FileRegistry[]): FileRegistry;
+export declare const minimumEdition: SupportedEdition, maximumEdition: SupportedEdition;