@bufbuild/protobuf 1.9.0 → 2.0.0-alpha.2

package/dist/esm/wire/base64-encoding.js

@@ -0,0 +1,151 @@
+// 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.
+/* eslint-disable @typescript-eslint/ban-ts-comment, @typescript-eslint/no-unnecessary-condition, prefer-const */
+/**
+ * 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 function base64Decode(base64Str) {
+    const table = getDecodeTable();
+    // estimate byte size, not accounting for inner padding and whitespace
+    let es = (base64Str.length * 3) / 4;
+    if (base64Str[base64Str.length - 2] == "=")
+        es -= 2;
+    else if (base64Str[base64Str.length - 1] == "=")
+        es -= 1;
+    let bytes = new Uint8Array(es), bytePos = 0, // position in byte array
+    groupPos = 0, // position in base64 group
+    b, // current byte
+    p = 0; // previous byte
+    for (let i = 0; i < base64Str.length; i++) {
+        b = table[base64Str.charCodeAt(i)];
+        if (b === undefined) {
+            switch (base64Str[i]) {
+                // @ts-expect-error TS7029: Fallthrough case in switch
+                case "=":
+                    groupPos = 0; // reset state when padding found
+                // eslint-disable-next-line no-fallthrough
+                case "\n":
+                case "\r":
+                case "\t":
+                case " ":
+                    continue; // skip white-space, and padding
+                default:
+                    throw Error("invalid base64 string.");
+            }
+        }
+        switch (groupPos) {
+            case 0:
+                p = b;
+                groupPos = 1;
+                break;
+            case 1:
+                bytes[bytePos++] = (p << 2) | ((b & 48) >> 4);
+                p = b;
+                groupPos = 2;
+                break;
+            case 2:
+                bytes[bytePos++] = ((p & 15) << 4) | ((b & 60) >> 2);
+                p = b;
+                groupPos = 3;
+                break;
+            case 3:
+                bytes[bytePos++] = ((p & 3) << 6) | b;
+                groupPos = 0;
+                break;
+        }
+    }
+    if (groupPos == 1)
+        throw Error("invalid base64 string.");
+    return bytes.subarray(0, bytePos);
+}
+/**
+ * Encode a byte array to a base64 string.
+ *
+ * By default, this function uses the standard base64 encoding with padding.
+ *
+ * To encode without padding, use encoding = "std_raw".
+ *
+ * To encode with the URL encoding, use encoding = "url", which replaces the
+ * characters +/ by their URL-safe counterparts -_, and omits padding.
+ */
+export function base64Encode(bytes, encoding = "std") {
+    const table = getEncodeTable(encoding);
+    const pad = encoding == "std";
+    let base64 = "", groupPos = 0, // position in base64 group
+    b, // current byte
+    p = 0; // carry over from previous byte
+    for (let i = 0; i < bytes.length; i++) {
+        b = bytes[i];
+        switch (groupPos) {
+            case 0:
+                base64 += table[b >> 2];
+                p = (b & 3) << 4;
+                groupPos = 1;
+                break;
+            case 1:
+                base64 += table[p | (b >> 4)];
+                p = (b & 15) << 2;
+                groupPos = 2;
+                break;
+            case 2:
+                base64 += table[p | (b >> 6)];
+                base64 += table[b & 63];
+                groupPos = 0;
+                break;
+        }
+    }
+    // add output padding
+    if (groupPos) {
+        base64 += table[p];
+        if (pad) {
+            base64 += "=";
+            if (groupPos == 1)
+                base64 += "=";
+        }
+    }
+    return base64;
+}
+// lookup table from base64 character to byte
+let encodeTableStd;
+let encodeTableUrl;
+// lookup table from base64 character *code* to byte because lookup by number is fast
+let decodeTable;
+function getEncodeTable(encoding) {
+    if (!encodeTableStd) {
+        encodeTableStd =
+            "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".split("");
+        encodeTableUrl = encodeTableStd.slice(0, -2).concat("-", "_");
+    }
+    return encoding == "url" ? encodeTableUrl : encodeTableStd;
+}
+function getDecodeTable() {
+    if (!decodeTable) {
+        decodeTable = [];
+        const encodeTable = getEncodeTable("std");
+        for (let i = 0; i < encodeTable.length; i++)
+            decodeTable[encodeTable[i].charCodeAt(0)] = i;
+        // support base64url variants
+        decodeTable["-".charCodeAt(0)] = encodeTable.indexOf("+");
+        decodeTable["_".charCodeAt(0)] = encodeTable.indexOf("/");
+    }
+    return decodeTable;
+}

package/dist/esm/wire/binary-encoding.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Protobuf binary format wire types.
+ *
+ * A wire type provides just enough information to find the length of the
+ * following value.
+ *
+ * See https://developers.google.com/protocol-buffers/docs/encoding#structure
+ */
+export declare enum WireType {
+    /**
+     * Used for int32, int64, uint32, uint64, sint32, sint64, bool, enum
+     */
+    Varint = 0,
+    /**
+     * Used for fixed64, sfixed64, double.
+     * Always 8 bytes with little-endian byte order.
+     */
+    Bit64 = 1,
+    /**
+     * Used for string, bytes, embedded messages, packed repeated fields
+     *
+     * Only repeated numeric types (types which use the varint, 32-bit,
+     * or 64-bit wire types) can be packed. In proto3, such fields are
+     * packed by default.
+     */
+    LengthDelimited = 2,
+    /**
+     * Start of a tag-delimited aggregate, such as a proto2 group, or a message
+     * in editions with message_encoding = DELIMITED.
+     */
+    StartGroup = 3,
+    /**
+     * End of a tag-delimited aggregate.
+     */
+    EndGroup = 4,
+    /**
+     * Used for fixed32, sfixed32, float.
+     * Always 4 bytes with little-endian byte order.
+     */
+    Bit32 = 5
+}
+export declare class BinaryWriter {
+    private readonly encodeUtf8;
+    /**
+     * We cannot allocate a buffer for the entire output
+     * because we don't know it's size.
+     *
+     * So we collect smaller chunks of known size and
+     * concat them later.
+     *
+     * Use `raw()` to push data to this array. It will flush
+     * `buf` first.
+     */
+    private chunks;
+    /**
+     * A growing buffer for byte values. If you don't know
+     * the size of the data you are writing, push to this
+     * array.
+     */
+    protected buf: number[];
+    /**
+     * Previous fork states.
+     */
+    private stack;
+    constructor(encodeUtf8?: (text: string) => Uint8Array);
+    /**
+     * Return all bytes written and reset this writer.
+     */
+    finish(): Uint8Array;
+    /**
+     * Start a new fork for length-delimited data like a message
+     * or a packed repeated field.
+     *
+     * Must be joined later with `join()`.
+     */
+    fork(): this;
+    /**
+     * Join the last fork. Write its length and bytes, then
+     * return to the previous state.
+     */
+    join(): this;
+    /**
+     * Writes a tag (field number and wire type).
+     *
+     * Equivalent to `uint32( (fieldNo << 3 | type) >>> 0 )`.
+     *
+     * Generated code should compute the tag ahead of time and call `uint32()`.
+     */
+    tag(fieldNo: number, type: WireType): this;
+    /**
+     * Write a chunk of raw bytes.
+     */
+    raw(chunk: Uint8Array): this;
+    /**
+     * Write a `uint32` value, an unsigned 32 bit varint.
+     */
+    uint32(value: number): this;
+    /**
+     * Write a `int32` value, a signed 32 bit varint.
+     */
+    int32(value: number): this;
+    /**
+     * Write a `bool` value, a variant.
+     */
+    bool(value: boolean): this;
+    /**
+     * Write a `bytes` value, length-delimited arbitrary data.
+     */
+    bytes(value: Uint8Array): this;
+    /**
+     * Write a `string` value, length-delimited data converted to UTF-8 text.
+     */
+    string(value: string): this;
+    /**
+     * Write a `float` value, 32-bit floating point number.
+     */
+    float(value: number): this;
+    /**
+     * Write a `double` value, a 64-bit floating point number.
+     */
+    double(value: number): this;
+    /**
+     * Write a `fixed32` value, an unsigned, fixed-length 32-bit integer.
+     */
+    fixed32(value: number): this;
+    /**
+     * Write a `sfixed32` value, a signed, fixed-length 32-bit integer.
+     */
+    sfixed32(value: number): this;
+    /**
+     * Write a `sint32` value, a signed, zigzag-encoded 32-bit varint.
+     */
+    sint32(value: number): this;
+    /**
+     * Write a `fixed64` value, a signed, fixed-length 64-bit integer.
+     */
+    sfixed64(value: string | number | bigint): this;
+    /**
+     * Write a `fixed64` value, an unsigned, fixed-length 64 bit integer.
+     */
+    fixed64(value: string | number | bigint): this;
+    /**
+     * Write a `int64` value, a signed 64-bit varint.
+     */
+    int64(value: string | number | bigint): this;
+    /**
+     * Write a `sint64` value, a signed, zig-zag-encoded 64-bit varint.
+     */
+    sint64(value: string | number | bigint): this;
+    /**
+     * Write a `uint64` value, an unsigned 64-bit varint.
+     */
+    uint64(value: string | number | bigint): this;
+}
+export declare class BinaryReader {
+    private readonly decodeUtf8;
+    /**
+     * Current position.
+     */
+    pos: number;
+    /**
+     * Number of bytes available in this reader.
+     */
+    readonly len: number;
+    protected readonly buf: Uint8Array;
+    private readonly view;
+    constructor(buf: Uint8Array, decodeUtf8?: (bytes: Uint8Array) => string);
+    /**
+     * Reads a tag - field number and wire type.
+     */
+    tag(): [number, WireType];
+    /**
+     * Skip one element and return the skipped data.
+     *
+     * When skipping StartGroup, provide the tags field number to check for
+     * matching field number in the EndGroup tag.
+     */
+    skip(wireType: WireType, fieldNo?: number): Uint8Array;
+    protected varint64: () => [number, number];
+    /**
+     * Throws error if position in byte array is out of range.
+     */
+    protected assertBounds(): void;
+    /**
+     * Read a `uint32` field, an unsigned 32 bit varint.
+     */
+    uint32: () => number;
+    /**
+     * Read a `int32` field, a signed 32 bit varint.
+     */
+    int32(): number;
+    /**
+     * Read a `sint32` field, a signed, zigzag-encoded 32-bit varint.
+     */
+    sint32(): number;
+    /**
+     * Read a `int64` field, a signed 64-bit varint.
+     */
+    int64(): bigint | string;
+    /**
+     * Read a `uint64` field, an unsigned 64-bit varint.
+     */
+    uint64(): bigint | string;
+    /**
+     * Read a `sint64` field, a signed, zig-zag-encoded 64-bit varint.
+     */
+    sint64(): bigint | string;
+    /**
+     * Read a `bool` field, a variant.
+     */
+    bool(): boolean;
+    /**
+     * Read a `fixed32` field, an unsigned, fixed-length 32-bit integer.
+     */
+    fixed32(): number;
+    /**
+     * Read a `sfixed32` field, a signed, fixed-length 32-bit integer.
+     */
+    sfixed32(): number;
+    /**
+     * Read a `fixed64` field, an unsigned, fixed-length 64 bit integer.
+     */
+    fixed64(): bigint | string;
+    /**
+     * Read a `fixed64` field, a signed, fixed-length 64-bit integer.
+     */
+    sfixed64(): bigint | string;
+    /**
+     * Read a `float` field, 32-bit floating point number.
+     */
+    float(): number;
+    /**
+     * Read a `double` field, a 64-bit floating point number.
+     */
+    double(): number;
+    /**
+     * Read a `bytes` field, length-delimited arbitrary data.
+     */
+    bytes(): Uint8Array;
+    /**
+     * Read a `string` field, length-delimited data converted to UTF-8 text.
+     */
+    string(): string;
+}

package/dist/esm/{binary-encoding.js → wire/binary-encoding.js}

@@ -11,9 +11,10 @@
 // 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 { varint32read, varint32write, varint64read, varint64write, } from "./google/varint.js";
-import { assertFloat32, assertInt32, assertUInt32 } from "./private/assert.js";
-import { protoInt64 } from "./proto-int64.js";
+import { varint32read, varint32write, varint64read, varint64write, } from "./varint.js";
+import { assertFloat32, assertInt32, assertUInt32 } from "../reflect/assert.js";
+import { protoInt64 } from "../proto-int64.js";
+import { getTextEncoding } from "./text-encoding.js";
 /* eslint-disable prefer-const,no-case-declarations,@typescript-eslint/restrict-plus-operands */
 /**
  * Protobuf binary format wire types.
@@ -58,12 +59,12 @@ export var WireType;
     WireType[WireType["Bit32"] = 5] = "Bit32";
 })(WireType || (WireType = {}));
 export class BinaryWriter {
-    constructor(textEncoder) {
+    constructor(encodeUtf8 = getTextEncoding().encodeUtf8) {
+        this.encodeUtf8 = encodeUtf8;
         /**
          * Previous fork states.
          */
         this.stack = [];
-        this.textEncoder = textEncoder !== null && textEncoder !== void 0 ? textEncoder : new TextEncoder();
         this.chunks = [];
         this.buf = [];
     }
@@ -173,7 +174,7 @@ export class BinaryWriter {
      * Write a `string` value, length-delimited data converted to UTF-8 text.
      */
     string(value) {
-        let chunk = this.textEncoder.encode(value);
+        let chunk = this.encodeUtf8(value);
         this.uint32(chunk.byteLength); // write length of chunk as varint
         return this.raw(chunk);
     }
@@ -268,17 +269,17 @@ export class BinaryWriter {
     }
 }
 export class BinaryReader {
-    constructor(buf, textDecoder) {
+    constructor(buf, decodeUtf8 = getTextEncoding().decodeUtf8) {
+        this.decodeUtf8 = decodeUtf8;
         this.varint64 = varint64read; // dirty cast for `this`
         /**
          * Read a `uint32` field, an unsigned 32 bit varint.
          */
-        this.uint32 = varint32read; // dirty cast for `this` and access to protected `buf`
+        this.uint32 = varint32read;
         this.buf = buf;
         this.len = buf.length;
         this.pos = 0;
         this.view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
-        this.textDecoder = textDecoder !== null && textDecoder !== void 0 ? textDecoder : new TextDecoder();
     }
     /**
      * Reads a tag - field number and wire type.
@@ -290,10 +291,12 @@ export class BinaryReader {
         return [fieldNo, wireType];
     }
     /**
-     * Skip one element on the wire and return the skipped data.
-     * Supports WireType.StartGroup since v2.0.0-alpha.23.
+     * Skip one element and return the skipped data.
+     *
+     * When skipping StartGroup, provide the tags field number to check for
+     * matching field number in the EndGroup tag.
      */
-    skip(wireType) {
+    skip(wireType, fieldNo) {
         let start = this.pos;
         switch (wireType) {
             case WireType.Varint:
@@ -302,11 +305,10 @@ export class BinaryReader {
                 }
                 break;
             // eslint-disable-next-line
-            // @ts-ignore TS7029: Fallthrough case in switch
+            // @ts-expect-error TS7029: Fallthrough case in switch
             case WireType.Bit64:
                 this.pos += 4;
-            // eslint-disable-next-line
-            // @ts-ignore TS7029: Fallthrough case in switch
+            // eslint-disable-next-line no-fallthrough
             case WireType.Bit32:
                 this.pos += 4;
                 break;
@@ -315,10 +317,15 @@ export class BinaryReader {
                 this.pos += len;
                 break;
             case WireType.StartGroup:
-                // TODO check for matching field numbers in StartGroup / EndGroup tags
-                let t;
-                while ((t = this.tag()[1]) !== WireType.EndGroup) {
-                    this.skip(t);
+                for (;;) {
+                    const [fn, wt] = this.tag();
+                    if (wt === WireType.EndGroup) {
+                        if (fieldNo !== undefined && fn !== fieldNo) {
+                            throw new Error("invalid end group tag");
+                        }
+                        break;
+                    }
+                    this.skip(wt, fn);
                 }
                 break;
             default:
@@ -427,6 +434,6 @@ export class BinaryReader {
      * Read a `string` field, length-delimited data converted to UTF-8 text.
      */
     string() {
-        return this.textDecoder.decode(this.bytes());
+        return this.decodeUtf8(this.bytes());
     }
 }

package/dist/esm/wire/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./binary-encoding.js";
+export * from "./base64-encoding.js";
+export * from "./text-encoding.js";
+export * from "./text-format.js";
+export * from "./size-delimited.js";

package/dist/esm/wire/index.js

@@ -0,0 +1,18 @@
+// 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.
+export * from "./binary-encoding.js";
+export * from "./base64-encoding.js";
+export * from "./text-encoding.js";
+export * from "./text-format.js";
+export * from "./size-delimited.js";

package/dist/esm/wire/size-delimited.d.ts

@@ -0,0 +1,51 @@
+import type { DescMessage } from "../desc-types.js";
+import type { BinaryWriteOptions } from "../to-binary.js";
+import type { MessageShape } from "../types.js";
+import type { BinaryReadOptions } from "../from-binary.js";
+/**
+ * Serialize a message, prefixing it with its size.
+ *
+ * A size-delimited message is a varint size in bytes, followed by exactly
+ * that many bytes of a message serialized with the binary format.
+ *
+ * This size-delimited format is compatible with other implementations.
+ * For details, see https://github.com/protocolbuffers/protobuf/issues/10229
+ */
+export declare function sizeDelimitedEncode<Desc extends DescMessage>(messageDesc: Desc, message: MessageShape<Desc>, options?: BinaryWriteOptions): Uint8Array;
+/**
+ * Parse a stream of size-delimited messages.
+ *
+ * A size-delimited message is a varint size in bytes, followed by exactly
+ * that many bytes of a message serialized with the binary format.
+ *
+ * This size-delimited format is compatible with other implementations.
+ * For details, see https://github.com/protocolbuffers/protobuf/issues/10229
+ */
+export declare function sizeDelimitedDecodeStream<Desc extends DescMessage>(messageDesc: Desc, iterable: AsyncIterable<Uint8Array>, options?: BinaryReadOptions): AsyncGenerator<MessageShape<Desc>, void, unknown>;
+/**
+ * Decodes the size from the given size-delimited message, which may be
+ * incomplete.
+ *
+ * Returns an object with the following properties:
+ * - size: The size of the delimited message in bytes
+ * - offset: The offset in the given byte array where the message starts
+ * - eof: true
+ *
+ * If the size-delimited data does not include all bytes of the varint size,
+ * the following object is returned:
+ * - size: null
+ * - offset: null
+ * - eof: false
+ *
+ * This function can be used to implement parsing of size-delimited messages
+ * from a stream.
+ */
+export declare function sizeDelimitedPeek(data: Uint8Array): {
+    readonly eof: false;
+    readonly size: number;
+    readonly offset: number;
+} | {
+    readonly eof: true;
+    readonly size: null;
+    readonly offset: null;
+};