@bufbuild/protobuf 2.0.0-alpha.1 → 2.0.0-alpha.3

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

@@ -1,32 +1,151 @@
-import type { DescField, DescMessage, DescOneof } from "../desc-types.js";
+import { type DescField, type DescMessage, type DescOneof } from "../descriptors.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";
+import type { 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: NewListItem<Field>): FieldError | undefined;
+    }>(field: Field, value: ReflectAddListItemValue<Field>): FieldError | undefined;
+    /**
+     * Set a map entry.
+     */
     setMapEntry<Field extends DescField & {
         fieldKind: "map";
-    }>(field: Field, key: MapEntryKey, value: NewMapEntryValue<Field>): FieldError | undefined;
+    }>(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";
     };
@@ -60,7 +179,21 @@ export interface ReflectList<V = unknown> extends Iterable<V> {
     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";
     };
@@ -80,9 +213,15 @@ export interface ReflectMap<K extends MapEntryKey = MapEntryKey, V = unknown> ex
     clear(): void;
     [unsafeLocal]: Record<string, unknown>;
 }
+/**
+ * A ReflectMap key.
+ */
 export type MapEntryKey = string | number | bigint | boolean;
 type enumVal = number;
-type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
+/**
+ * The return type of ReflectMessage.get()
+ */
+export type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
     fieldKind: "map";
 } ? (Field extends {
     mapKind: "message";
@@ -91,29 +230,35 @@ type ReflectGetValue<Field extends DescField = DescField> = (Field extends {
 } ? ReflectMap<MapEntryKey, enumVal> : Field extends {
     mapKind: "scalar";
     scalar: infer T;
-} ? ReflectMap<MapEntryKey, ScalarValue<T, LongType.BIGINT>> : never) : Field extends {
+} ? ReflectMap<MapEntryKey, ScalarValue<T>> : never) : Field extends {
     fieldKind: "list";
 } ? ReflectList : Field extends {
     fieldKind: "enum";
-} ? number | undefined : Field extends {
+} ? number : Field extends {
     fieldKind: "message";
 } ? ReflectMessage : Field extends {
     fieldKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T> | undefined : never);
-type ReflectSetValue<Field extends DescField = DescField> = (Field extends {
+} ? 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 | undefined : Field extends {
+} ? number : Field extends {
     fieldKind: "message";
 } ? ReflectMessage : Field extends {
     fieldKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T> | undefined : never);
-type NewListItem<Field extends DescField & {
+} ? ScalarValue<T> : never);
+/**
+ * The type of the "value" argument of ReflectMessage.addListItem()
+ */
+export type ReflectAddListItemValue<Field extends DescField & {
     fieldKind: "list";
 }> = (Field extends {
     listKind: "scalar";
@@ -123,7 +268,10 @@ type NewListItem<Field extends DescField & {
 } ? enumVal : Field extends {
     listKind: "message";
 } ? ReflectMessage : never);
-type NewMapEntryValue<Field extends DescField & {
+/**
+ * The type of the "value" argument of ReflectMessage.setMapEntry()
+ */
+export type ReflectSetMapEntryValue<Field extends DescField & {
     fieldKind: "map";
 }> = (Field extends {
     mapKind: "enum";
@@ -132,5 +280,5 @@ type NewMapEntryValue<Field extends DescField & {
 } ? ReflectMessage : Field extends {
     mapKind: "scalar";
     scalar: infer T;
-} ? ScalarValue<T, LongType.BIGINT> : never);
+} ? ScalarValue<T> : never);
 export {};

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

@@ -1,6 +1,9 @@
-import type { DescField, DescMessage } from "../desc-types.js";
+import { type DescField, type DescMessage } from "../descriptors.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,
@@ -15,9 +18,15 @@ export declare function reflect<Desc extends DescMessage>(messageDesc: Desc, mes
      */
     disableFieldValueCheck?: boolean;
 }): ReflectMessage;
+/**
+ * Create a ReflectList.
+ */
 export declare function reflectList<V>(field: DescField & {
     fieldKind: "list";
-}, unsafeInput?: unknown[]): ReflectList<V>;
+}, 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>): ReflectMap<K, V>;
+}, unsafeInput?: Record<string, unknown>, check?: boolean): ReflectMap<K, V>;