@bufbuild/protobuf 0.0.1-alpha.1

package/dist/types/message.d.ts

@@ -0,0 +1,124 @@
+import type { BinaryReadOptions, BinaryWriteOptions } from "./binary-format.js";
+import type {
+  JsonReadOptions,
+  JsonValue,
+  JsonWriteOptions,
+  JsonWriteStringOptions,
+} from "./json-format.js";
+import type { MessageType } from "./message-type.js";
+/**
+ * AnyMessage is an interface implemented by all messages. If you need to
+ * handle messages of unknown type, this interface provides a convenient
+ * index signature to access fields with message["fieldname"].
+ */
+export interface AnyMessage extends Message<AnyMessage> {
+  [k: string]: any;
+}
+/**
+ * Message is the base class of every message, generated, or created at
+ * runtime.
+ *
+ * It is _not_ safe to extend this class. If you want to create a message at
+ * run time, use proto3.makeMessageType().
+ */
+export declare class Message<T extends Message<T> = AnyMessage> {
+  /**
+   * Compare with a message of the same type.
+   */
+  equals(other: T | PlainMessage<T> | undefined): boolean;
+  /**
+   * Create a deep copy.
+   */
+  clone(): T;
+  /**
+   * Parse from binary data, merging fields.
+   *
+   * 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.
+   */
+  fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): this;
+  /**
+   * Parse a message from a JSON value.
+   */
+  fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): this;
+  /**
+   * Parse a message from a JSON string.
+   */
+  fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): this;
+  /**
+   * Serialize the message to binary data.
+   */
+  toBinary(options?: Partial<BinaryWriteOptions>): Uint8Array;
+  /**
+   * Serialize the message to a JSON value, a JavaScript value that can be
+   * passed to JSON.stringify().
+   */
+  toJson(options?: Partial<JsonWriteOptions>): JsonValue;
+  /**
+   * Serialize the message to a JSON string.
+   */
+  toJsonString(options?: Partial<JsonWriteStringOptions>): string;
+  /**
+   * Retrieve the MessageType of this message - a singleton that represents
+   * the protobuf message declaration and provides metadata for reflection-
+   * based operations.
+   */
+  getType(): MessageType<T>;
+}
+/**
+ * PlainMessage<T> strips all methods from a message, leaving only fields
+ * and oneof groups.
+ */
+export declare type PlainMessage<T extends Message> = {
+  [P in keyof T as T[P] extends Function ? never : P]: T[P];
+};
+/**
+ * PartialMessage<T> constructs a type from a message. The resulting type
+ * only contains the protobuf field members of the message, and all of them
+ * are optional.
+ *
+ * PartialMessage is similar to the built-in type Partial<T>, but recursive,
+ * and respects `oneof` groups.
+ */
+export declare type PartialMessage<T extends Message> = {
+  [P in keyof T as T[P] extends Function ? never : P]?: PartialField<T[P]>;
+};
+declare type PartialField<F> = F extends
+  | Date
+  | Uint8Array
+  | bigint
+  | boolean
+  | string
+  | number
+  ? F
+  : F extends Array<infer U>
+  ? Array<PartialField<U>>
+  : F extends ReadonlyArray<infer U>
+  ? ReadonlyArray<PartialField<U>>
+  : F extends OneofSelectedMessage<infer C, infer V>
+  ? {
+      case: C;
+      value: PartialMessage<V>;
+    }
+  : F extends {
+      case: string | undefined;
+      value?: unknown;
+    }
+  ? F
+  : F extends Message
+  ? PartialMessage<F>
+  : F extends {
+      [key: string | number]: Message<infer U>;
+    }
+  ? {
+      [key: string | number]: PartialMessage<U>;
+    }
+  : F;
+declare type OneofSelectedMessage<K extends string, M extends Message> = {
+  case: K;
+  value: M;
+};
+export {};

package/dist/types/private/assert.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Assert that condition is truthy or throw error (with message)
+ */
+export declare function assert(
+  condition: unknown,
+  msg?: string
+): asserts condition;
+/**
+ * Assert a valid signed protobuf 32-bit integer.
+ */
+export declare function assertInt32(arg: unknown): asserts arg is number;
+/**
+ * Assert a valid unsigned protobuf 32-bit integer.
+ */
+export declare function assertUInt32(arg: unknown): asserts arg is number;
+/**
+ * Assert a valid protobuf float value.
+ */
+export declare function assertFloat32(arg: unknown): asserts arg is number;

package/dist/types/private/base64.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Decodes a base64 string to a byte array.
+ *
+ * - ignores white-space, including line breaks and tabs
+ * - allows inner padding (can decode concatenated base64 strings)
+ * - does not require padding
+ * - understands base64url encoding:
+ *   "-" instead of "+",
+ *   "_" instead of "/",
+ *   no padding
+ */
+export declare function base64decode(base64Str: string): Uint8Array;
+/**
+ * Encodes a byte array to a base64 string.
+ * Adds padding at the end.
+ * Does not insert newlines.
+ */
+export declare function base64encode(bytes: Uint8Array): string;

package/dist/types/private/binary-format-common.d.ts

@@ -0,0 +1,38 @@
+import { IBinaryWriter } from "../binary-encoding.js";
+import type { BinaryWriteOptions } from "../binary-format.js";
+import type { BinaryFormat } from "../binary-format.js";
+import { FieldInfo, ScalarType } from "../field.js";
+import type { MessageType } from "../message-type.js";
+export declare function makeBinaryFormatCommon(): Omit<
+  BinaryFormat,
+  "writeMessage"
+>;
+export declare function writeMapEntry(
+  writer: IBinaryWriter,
+  options: BinaryWriteOptions,
+  field: FieldInfo & {
+    kind: "map";
+  },
+  key: any,
+  value: any
+): void;
+export declare function writeMessageField(
+  writer: IBinaryWriter,
+  options: BinaryWriteOptions,
+  type: MessageType,
+  fieldNo: number,
+  value: any
+): void;
+export declare function writeScalar(
+  writer: IBinaryWriter,
+  type: ScalarType,
+  fieldNo: number,
+  value: any,
+  emitIntrinsicDefault: boolean
+): void;
+export declare function writePacked(
+  writer: IBinaryWriter,
+  type: ScalarType,
+  fieldNo: number,
+  value: any[]
+): void;

package/dist/types/private/binary-format-proto2.d.ts

@@ -0,0 +1,2 @@
+import type { BinaryFormat } from "../binary-format.js";
+export declare function makeBinaryFormatProto2(): BinaryFormat;

package/dist/types/private/binary-format-proto3.d.ts

@@ -0,0 +1,2 @@
+import type { BinaryFormat } from "../binary-format.js";
+export declare function makeBinaryFormatProto3(): BinaryFormat;

package/dist/types/private/enum.d.ts

@@ -0,0 +1,29 @@
+import type { EnumType, EnumValueInfo } from "../enum.js";
+/**
+ * Represents a generated enum.
+ */
+export interface EnumObject {
+  [key: number]: string;
+  [k: string]: number | string;
+}
+/**
+ * Get reflection information from a generated enum.
+ * If this function is called on something other than a generated
+ * enum, it raises an error.
+ */
+export declare function getEnumType(enumObject: EnumObject): EnumType;
+/**
+ * Sets reflection information on a generated enum.
+ */
+export declare function setEnumType(
+  enumObject: EnumObject,
+  typeName: string,
+  values: EnumValueInfo[]
+): void;
+/**
+ * Create a new EnumType with the given values.
+ */
+export declare function makeEnumType(
+  typeName: string,
+  values: EnumValueInfo[]
+): EnumType;

package/dist/types/private/field-list.d.ts

@@ -0,0 +1,25 @@
+import type { FieldInfo, OneofInfo, PartialFieldInfo } from "../field.js";
+import type { FieldList } from "../field-list.js";
+export declare type FieldListSource =
+  | readonly PartialFieldInfo[]
+  | readonly FieldInfo[]
+  | (() => readonly PartialFieldInfo[])
+  | (() => readonly FieldInfo[]);
+export declare class InternalFieldList implements FieldList {
+  private readonly _fields;
+  private readonly _normalizer;
+  private all?;
+  private numbersAsc?;
+  private jsonNames?;
+  private numbers?;
+  private members?;
+  constructor(
+    fields: FieldListSource,
+    normalizer: (p: FieldListSource) => FieldInfo[]
+  );
+  findJsonName(jsonName: string): FieldInfo | undefined;
+  find(fieldNo: number): FieldInfo | undefined;
+  list(): readonly FieldInfo[];
+  byNumber(): readonly FieldInfo[];
+  byMember(): readonly (FieldInfo | OneofInfo)[];
+}

package/dist/types/private/field-wrapper.d.ts

@@ -0,0 +1,27 @@
+import type { Message } from "../message.js";
+import type { MessageType } from "../message-type.js";
+/**
+ * A field wrapper unwraps a message to a primitive value that is more
+ * ergonomic for use as a message field.
+ *
+ * Note that this feature exists for google/protobuf/{wrappers,struct}.proto
+ * and cannot be used to arbitrarily modify types in generated code.
+ */
+export interface FieldWrapper<T extends Message<T> = any, U = any> {
+  wrapField(value: U): T;
+  unwrapField(value: T): U;
+}
+/**
+ * Wrap field values whose message type has a wrapper.
+ */
+export declare function wrapField<T extends Message<T>>(
+  type: MessageType<T>,
+  value: any
+): T;
+/**
+ * Unwrap field values whose message type has a wrapper.
+ */
+export declare function unwrapField<T extends Message<T>>(
+  type: MessageType<T>,
+  value: T
+): any;

package/dist/types/private/field.d.ts

@@ -0,0 +1,15 @@
+import type { FieldInfo, OneofInfo } from "../field.js";
+export declare class InternalOneofInfo implements OneofInfo {
+  readonly kind = "oneof";
+  readonly name: string;
+  readonly localName: string;
+  readonly repeated = false;
+  readonly packed = false;
+  readonly opt = false;
+  readonly default: undefined;
+  readonly fields: FieldInfo[];
+  private _lookup?;
+  constructor(name: string);
+  addField(field: FieldInfo): void;
+  findField(localName: string): FieldInfo | undefined;
+}

package/dist/types/private/json-format-common.d.ts

@@ -0,0 +1,30 @@
+import type {
+  JsonFormat,
+  JsonValue,
+  JsonWriteOptions,
+} from "../json-format.js";
+import { FieldInfo, ScalarType } from "../field.js";
+import type { EnumType } from "../enum.js";
+declare type JsonFormatWriteFieldFn = (
+  field: FieldInfo,
+  value: any,
+  options: JsonWriteOptions
+) => JsonValue | undefined;
+export declare function makeJsonFormatCommon(
+  makeWriteField: (
+    writeEnumFn: typeof writeEnum,
+    writeScalarFn: typeof writeScalar
+  ) => JsonFormatWriteFieldFn
+): JsonFormat;
+declare function writeEnum(
+  type: EnumType,
+  value: number | undefined,
+  emitIntrinsicDefault: boolean,
+  enumAsInteger: boolean
+): JsonValue | undefined;
+declare function writeScalar(
+  type: ScalarType,
+  value: any,
+  emitIntrinsicDefault: boolean
+): JsonValue | undefined;
+export {};

package/dist/types/private/json-format-proto2.d.ts

@@ -0,0 +1,2 @@
+import type { JsonFormat } from "../json-format.js";
+export declare function makeJsonFormatProto2(): JsonFormat;

package/dist/types/private/json-format-proto3.d.ts

@@ -0,0 +1,2 @@
+import type { JsonFormat } from "../json-format.js";
+export declare function makeJsonFormatProto3(): JsonFormat;

package/dist/types/private/message-type.d.ts

@@ -0,0 +1,15 @@
+import { AnyMessage, Message } from "../message.js";
+import type { FieldListSource } from "./field-list.js";
+import type { MessageType } from "../message-type.js";
+import type { ProtoRuntime } from "./proto-runtime.js";
+/**
+ * Create a new message type using the given runtime.
+ */
+export declare function makeMessageType<T extends Message<T> = AnyMessage>(
+  runtime: ProtoRuntime,
+  typeName: string,
+  fields: FieldListSource,
+  opt?: {
+    localName?: string;
+  }
+): MessageType<T>;

package/dist/types/private/names.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns the JSON name for a protobuf field, exactly like protoc does.
+ */
+export declare function makeJsonName(protoName: string): string;
+/**
+ * Returns the local name of a field, exactly like protoc-gen-es does.
+ */
+export declare function makeFieldName(
+  protoName: string,
+  inOneof: boolean
+): string;
+/**
+ * Returns the local name of a oneof group, exactly like protoc-gen-es does.
+ */
+export declare function makeOneofName(protoName: string): string;
+/**
+ * Returns the local name of a rpc, exactly like protoc-gen-es does.
+ */
+export declare function makeMethodName(protoName: string): string;

package/dist/types/private/options-map.d.ts

@@ -0,0 +1,7 @@
+import type { JsonValue } from "../json-format";
+/**
+ *
+ */
+export declare type OptionsMap = {
+  readonly [extensionName: string]: JsonValue;
+};

package/dist/types/private/proto-runtime.d.ts

@@ -0,0 +1,55 @@
+import type { JsonFormat, JsonValue } from "../json-format.js";
+import type { BinaryFormat } from "../binary-format.js";
+import type { AnyMessage } from "../message.js";
+import type { Message } from "../message.js";
+import type { EnumType, EnumValueInfo } from "../enum.js";
+import type { MessageType } from "../message-type.js";
+import type { FieldListSource } from "./field-list.js";
+import type { EnumObject } from "./enum.js";
+import type { Util } from "./util.js";
+/**
+ * A facade that provides serialization and other internal functionality.
+ */
+export interface ProtoRuntime {
+  readonly syntax: string;
+  readonly json: JsonFormat;
+  readonly bin: BinaryFormat;
+  readonly util: Util;
+  /**
+   * Create a message type at runtime, without generating code.
+   */
+  makeMessageType<T extends Message<T> = AnyMessage>(
+    typeName: string,
+    fields: FieldListSource,
+    opt?: {
+      localName?: string;
+      options?: {
+        readonly [extensionName: string]: JsonValue;
+      };
+    }
+  ): MessageType<T>;
+  /**
+   * Create an enum type at runtime, without generating code.
+   */
+  makeEnumType(
+    typeName: string,
+    values: EnumValueInfo[],
+    opt?: {
+      options?: {
+        readonly [extensionName: string]: JsonValue;
+      };
+    }
+  ): EnumType;
+  /**
+   * Get reflection information from a generated enum.
+   * If this function is called on something other than a generated
+   * enum, it raises an error.
+   */
+  getEnumType(enumObject: EnumObject): EnumType;
+}
+export declare function makeProtoRuntime(
+  syntax: string,
+  json: JsonFormat,
+  bin: BinaryFormat,
+  util: Util
+): ProtoRuntime;

package/dist/types/private/scalars.d.ts

@@ -0,0 +1,33 @@
+import { ScalarType } from "../field.js";
+import { IBinaryWriter, WireType } from "../binary-encoding.js";
+/**
+ * Returns true if both scalar values are equal.
+ */
+export declare function scalarEquals(
+  type: ScalarType,
+  a: string | boolean | number | bigint | Uint8Array | undefined,
+  b: string | boolean | number | bigint | Uint8Array | undefined
+): boolean;
+/**
+ * Returns the default value for the given scalar type, following
+ * proto3 semantics.
+ */
+export declare function scalarDefaultValue(type: ScalarType): any;
+/**
+ * Get information for writing a scalar value.
+ *
+ * Returns tuple:
+ * [0]: appropriate WireType
+ * [1]: name of the appropriate method of IBinaryWriter
+ * [2]: whether the given value is a default value for proto3 semantics
+ *
+ * If argument `value` is omitted, [2] is always false.
+ */
+export declare function scalarTypeInfo(
+  type: ScalarType,
+  value?: any
+): [
+  WireType,
+  Exclude<keyof IBinaryWriter, "tag" | "raw" | "fork" | "join" | "finish">,
+  boolean
+];

package/dist/types/private/util-common.d.ts

@@ -0,0 +1,5 @@
+import type { Util } from "./util.js";
+export declare function makeUtilCommon(): Omit<
+  Util,
+  "newFieldList" | "initFields"
+>;

package/dist/types/private/util.d.ts

@@ -0,0 +1,55 @@
+import type { FieldListSource } from "./field-list.js";
+import type { FieldList } from "../field-list.js";
+import type { EnumObject } from "./enum.js";
+import type { JsonValue } from "../json-format.js";
+import type { Message, PartialMessage, PlainMessage } from "../message.js";
+import type { MessageType } from "../message-type.js";
+import type { EnumValueInfo } from "../enum.js";
+/**
+ * Provides utilities used by generated code.
+ * All methods are internal and are not safe to use, they may break with a
+ * future release.
+ */
+export interface Util {
+  /**
+   * Create a field list
+   */
+  newFieldList(fields: FieldListSource): FieldList;
+  /**
+   * Sets reflection information on a generated enum.
+   */
+  setEnumType(
+    enumObject: EnumObject,
+    typeName: string,
+    values: EnumValueInfo[],
+    opt?: {
+      options?: {
+        readonly [extensionName: string]: JsonValue;
+      };
+    }
+  ): void;
+  /**
+   * Set default field values on the target message.
+   */
+  initFields(target: Message): void;
+  /**
+   * Set specified field values on the target message, recursively.
+   */
+  initPartial<T extends Message<T>>(
+    source: PartialMessage<T> | undefined,
+    target: T
+  ): void;
+  /**
+   * Compares two messages of the same type recursively.
+   * Will also return true if both messages are `undefined`.
+   */
+  equals<T extends Message<T>>(
+    type: MessageType,
+    a: T | PlainMessage<T> | undefined,
+    b: T | PlainMessage<T> | undefined
+  ): boolean;
+  /**
+   * Create a deep copy.
+   */
+  clone<T extends Message<T>>(message: T): T;
+}

package/dist/types/proto-int64.d.ts

@@ -0,0 +1,94 @@
+/**
+ * We use the `bigint` primitive to represent 64-bit integral types. If bigint
+ * is unavailable, we fall back to a string representation, which means that
+ * all values typed as `bigint` will actually be strings.
+ *
+ * If your code is intended to run in an environment where bigint may be
+ * unavailable, it must handle both the bigint and the string representation.
+ * For presenting values, this is straight-forward with implicit or explicit
+ * conversion to string:
+ *
+ * ```ts
+ * let el = document.createElement("span");
+ * el.innerText = message.int64Field; // assuming a protobuf int64 field
+ *
+ * console.log(`int64: ${message.int64Field}`);
+ *
+ * let str: string = message.int64Field.toString();
+ * ```
+ *
+ * If you need to manipulate 64-bit integral values and are sure the values
+ * can be safely represented as an IEEE-754 double precision number, you can
+ * convert to a JavaScript Number:
+ *
+ * ```ts
+ * console.log(message.int64Field.toString())
+ * let num = Number(message.int64Field);
+ * num = num + 1;
+ * message.int64Field = protoInt64.parse(num);
+ * ```
+ *
+ * If you need to manipulate 64-bit integral values that are outside the
+ * range of safe representation as Number, you can work with the two's
+ * complement directly. The following example negates a field value:
+ *
+ * ```ts
+ * let t = protoInt64.enc(message.int64Field);
+ * t.hi = ~t.hi;
+ * if (t.lo) {
+ *     t.lo = ~t.lo + 1;
+ * } else {
+ *     t.hi += 1;
+ * }
+ * message.int64Field = protoInt64.dec(t.lo, t.hi);
+ * ```
+ *
+ * There are several 3rd party libraries that provide arithmetic operations
+ * on a two's complement, for example the npm package "long".
+ */
+interface Int64Support {
+  /**
+   * 0n if bigint is available, "0" if unavailable.
+   */
+  readonly zero: bigint;
+  /**
+   * Is bigint available?
+   */
+  readonly supported: boolean;
+  /**
+   * Parse a signed 64-bit integer.
+   * Returns a bigint if available, a string otherwise.
+   */
+  parse(value: string | number | bigint): bigint;
+  /**
+   * Parse an unsigned 64-bit integer.
+   * Returns a bigint if available, a string otherwise.
+   */
+  uParse(value: string | number | bigint): bigint;
+  /**
+   * Convert a signed 64-bit integral value to a two's complement.
+   */
+  enc(value: string | number | bigint): {
+    lo: number;
+    hi: number;
+  };
+  /**
+   * Convert an unsigned 64-bit integral value to a two's complement.
+   */
+  uEnc(value: string | number | bigint): {
+    lo: number;
+    hi: number;
+  };
+  /**
+   * Convert a two's complement to a signed 64-bit integral value.
+   * Returns a bigint if available, a string otherwise.
+   */
+  dec(lo: number, hi: number): bigint;
+  /**
+   * Convert a two's complement to an unsigned 64-bit integral value.
+   * Returns a bigint if available, a string otherwise.
+   */
+  uDec(lo: number, hi: number): bigint;
+}
+export declare const protoInt64: Int64Support;
+export {};

package/dist/types/proto2.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Provides functionality for messages defined with the proto2 syntax.
+ */
+export declare const proto2: import("./private/proto-runtime.js").ProtoRuntime;

package/dist/types/proto3.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Provides functionality for messages defined with the proto3 syntax.
+ */
+export declare const proto3: import("./private/proto-runtime.js").ProtoRuntime;