@sachitv/avro-typescript 0.4.1 → 0.5.0

package/esm/serialization/tap.js

@@ -12,14 +12,19 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _ReadableTap_lengthHint;
 import { bigIntToSafeNumber } from "./conversion.js";
 import { compareUint8Arrays } from "./compare_bytes.js";
-import { readUIntLE } from "./read_uint_le.js";
-import { invert } from "./manipulate_bytes.js";
 import { decode, encode } from "./text_encoding.js";
+import { ReadBufferError, WriteBufferError } from "./buffers/buffer_error.js";
 import { InMemoryReadableBuffer, InMemoryWritableBuffer, } from "./buffers/in_memory_buffer.js";
-function assertValidPosition(pos) {
+function assertValidPosition(pos, isWritable = false) {
     if (!Number.isFinite(pos) || !Number.isInteger(pos) || pos < 0 ||
         Math.abs(pos) > Number.MAX_SAFE_INTEGER) {
-        throw new RangeError("Tap position must be an integer within the safe number range.");
+        const message = "Tap position must be an integer within the safe number range.";
+        if (isWritable) {
+            throw new WriteBufferError(message, pos, 0, 0);
+        }
+        else {
+            throw new ReadBufferError(message, pos, 0, 0);
+        }
     }
 }
 function isIReadableBuffer(value) {
@@ -94,11 +99,11 @@ export class ReadableTap extends TapBase {
      */
     async isValid() {
         try {
-            const probe = await this.buffer.read(this.pos, 0);
-            return probe !== undefined;
+            await this.buffer.read(this.pos, 0);
+            return true;
         }
         catch (err) {
-            if (err instanceof RangeError) {
+            if (err instanceof ReadBufferError) {
                 return false;
             }
             throw err;
@@ -119,30 +124,18 @@ export class ReadableTap extends TapBase {
             return new Uint8Array();
         }
         const bytes = await this.buffer.read(0, readLength);
-        if (bytes) {
-            return bytes.slice();
-        }
-        else {
-            return new Uint8Array();
-        }
+        return bytes.slice();
     }
     /**
      * Returns the buffer contents from the start up to the current cursor.
-     * @throws RangeError if the cursor has advanced past the buffer length.
+     * @throws ReadBufferError if the cursor has advanced past the buffer length.
      */
     async getValue() {
-        const bytes = await this.buffer.read(0, this.pos);
-        if (!bytes) {
-            throw new RangeError("Tap position exceeds buffer length.");
-        }
-        return bytes;
+        return await this.buffer.read(0, this.pos);
     }
     /** Retrieves the byte at the specified position in the buffer. */
     async getByteAt(position) {
         const bytes = await this.buffer.read(position, 1);
-        if (!bytes) {
-            throw new RangeError("Attempt to read beyond buffer bounds.");
-        }
         return bytes[0];
     }
     /**
@@ -204,15 +197,12 @@ export class ReadableTap extends TapBase {
     }
     /**
      * Reads a 32-bit little-endian floating point number.
-     * @throws RangeError if the read would exceed the buffer.
+     * @throws ReadBufferError if the read would exceed the buffer.
      */
     async readFloat() {
         const pos = this.pos;
         this.pos += 4;
         const bytes = await this.buffer.read(pos, 4);
-        if (!bytes) {
-            throw new RangeError("Attempt to read beyond buffer bounds.");
-        }
         const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
         return view.getFloat32(0, true);
     }
@@ -224,15 +214,12 @@ export class ReadableTap extends TapBase {
     }
     /**
      * Reads a 64-bit little-endian floating point number.
-     * @throws RangeError if the read would exceed the buffer.
+     * @throws ReadBufferError if the read would exceed the buffer.
      */
     async readDouble() {
         const pos = this.pos;
         this.pos += 8;
         const bytes = await this.buffer.read(pos, 8);
-        if (!bytes) {
-            throw new RangeError("Attempt to read beyond buffer bounds.");
-        }
         const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
         return view.getFloat64(0, true);
     }
@@ -245,16 +232,12 @@ export class ReadableTap extends TapBase {
     /**
      * Reads a fixed-length byte sequence into a new buffer.
      * @param len Number of bytes to read.
-     * @throws RangeError if the read exceeds the buffer.
+     * @throws ReadBufferError if the read exceeds the buffer.
      */
     async readFixed(len) {
         const pos = this.pos;
         this.pos += len;
-        const bytes = await this.buffer.read(pos, len);
-        if (!bytes) {
-            throw new RangeError("Attempt to read beyond buffer bounds.");
-        }
-        return bytes;
+        return await this.buffer.read(pos, len);
     }
     /**
      * Skips a fixed-length byte sequence.
@@ -265,7 +248,7 @@ export class ReadableTap extends TapBase {
     }
     /**
      * Reads a length-prefixed byte sequence.
-     * @throws RangeError if insufficient data remains.
+     * @throws ReadBufferError if insufficient data remains.
      */
     async readBytes() {
         const length = bigIntToSafeNumber(await this.readLong(), "readBytes length");
@@ -287,7 +270,7 @@ export class ReadableTap extends TapBase {
     }
     /**
      * Reads a length-prefixed UTF-8 string.
-     * @throws RangeError when the buffer is exhausted prematurely.
+     * @throws ReadBufferError when the buffer is exhausted prematurely.
      */
     async readString() {
         const len = bigIntToSafeNumber(await this.readLong(), "readString length");
@@ -367,38 +350,6 @@ export class ReadableTap extends TapBase {
         const bytes2 = await tap.readFixed(l2);
         return compareUint8Arrays(bytes1, bytes2);
     }
-    /**
-     * Decodes the next zig-zag encoded long into an 8-byte two's complement buffer.
-     */
-    async unpackLongBytes() {
-        const res = new Uint8Array(8);
-        let n = 0;
-        let i = 0; // Byte index in target buffer.
-        let j = 6; // Bit offset in current target buffer byte.
-        let pos = this.pos;
-        let b = await this.getByteAt(pos++);
-        const neg = b & 1;
-        res.fill(0);
-        // Accumulate the zig-zag decoded bits into the 8-byte buffer, emitting a byte once filled.
-        n |= (b & 0x7f) >> 1;
-        while (b & 0x80) {
-            b = await this.getByteAt(pos++);
-            n |= (b & 0x7f) << j;
-            j += 7;
-            if (j >= 8) {
-                j -= 8;
-                res[i++] = n;
-                n >>= 8;
-            }
-        }
-        res[i] = n;
-        if (neg) {
-            // The low bit captured the sign; invert to restore the original negative value.
-            invert(res, 8);
-        }
-        this.pos = pos;
-        return res;
-    }
 }
 _ReadableTap_lengthHint = new WeakMap();
 /**
@@ -411,7 +362,7 @@ export class WritableTap extends TapBase {
      * @param pos The initial position in the buffer (default 0).
      */
     constructor(buf, pos = 0) {
-        assertValidPosition(pos);
+        assertValidPosition(pos, true);
         let buffer;
         if (buf instanceof ArrayBuffer) {
             buffer = new InMemoryWritableBuffer(buf, pos);
@@ -456,10 +407,27 @@ export class WritableTap extends TapBase {
     }
     /**
      * Writes a zig-zag encoded 32-bit signed integer.
+     * Uses a 32-bit zig-zag + varint path to avoid BigInt casts for performance.
      * @param n Integer value to write.
      */
     async writeInt(n) {
-        await this.writeLong(BigInt(n));
+        if (typeof n !== "number" ||
+            !Number.isInteger(n) ||
+            n < -2147483648 ||
+            n > 2147483647) {
+            throw new RangeError(`Value ${n} out of range for Avro int (-2147483648..2147483647)`);
+        }
+        // Zigzag encode to an unsigned 32-bit integer:
+        // (n << 1) ^ (n >> 31)
+        let value = ((n << 1) ^ (n >> 31)) >>> 0;
+        const buf = new Uint8Array(5);
+        let i = 0;
+        while (value > 0x7f) {
+            buf[i++] = (value & 0x7f) | 0x80;
+            value >>>= 7;
+        }
+        buf[i++] = value;
+        await this.appendRawBytes(buf.subarray(0, i));
     }
     /**
      * Writes a zig-zag encoded 64-bit signed integer.
@@ -504,14 +472,12 @@ export class WritableTap extends TapBase {
     /**
      * Writes a fixed-length byte sequence from the provided buffer.
      * @param buf Source buffer to copy from.
-     * @param len Optional number of bytes to write; defaults to the buffer length.
      */
-    async writeFixed(buf, len) {
-        const length = len ?? buf.length;
-        if (length === 0) {
+    async writeFixed(buf) {
+        if (buf.length === 0) {
             return;
         }
-        await this.appendRawBytes(buf.slice(0, length));
+        await this.appendRawBytes(buf);
     }
     /**
      * Writes a length-prefixed byte sequence backed by the provided buffer.
@@ -520,7 +486,7 @@ export class WritableTap extends TapBase {
     async writeBytes(buf) {
         const len = buf.length;
         await this.writeLong(BigInt(len));
-        await this.writeFixed(buf, len);
+        await this.writeFixed(buf);
     }
     /**
      * Writes a length-prefixed UTF-8 string.
@@ -530,7 +496,7 @@ export class WritableTap extends TapBase {
         const encoded = encode(str);
         const len = encoded.length;
         await this.writeLong(BigInt(len));
-        await this.writeFixed(encoded, len);
+        await this.writeFixed(encoded);
     }
     /**
      * Writes a binary string as raw bytes without a length prefix.
@@ -547,59 +513,4 @@ export class WritableTap extends TapBase {
         }
         await this.appendRawBytes(bytes);
     }
-    /**
-     * Encodes an 8-byte two's complement integer into zig-zag encoded varint bytes.
-     * @param arr Buffer containing the 8-byte value to encode; reused during processing.
-     */
-    async packLongBytes(arr) {
-        const bufView = new DataView(arr.buffer, arr.byteOffset, arr.byteLength);
-        const neg = (bufView.getUint8(7) & 0x80) >> 7;
-        let j = 1;
-        let k = 0;
-        let m = 3;
-        let n;
-        if (neg) {
-            // Temporarily convert to magnitude so the zig-zag representation can strip the sign bit.
-            invert(arr, 8);
-            n = 1;
-        }
-        else {
-            n = 0;
-        }
-        const parts = [
-            readUIntLE(bufView, 0, 3),
-            readUIntLE(bufView, 3, 3),
-            readUIntLE(bufView, 6, 2),
-        ];
-        while (m && !parts[--m]) {
-            /* skip trailing zeros */
-        }
-        const emitted = [];
-        // Pack 24-bit chunks into the zig-zag bucket, flushing continuation bytes as needed.
-        while (k < m) {
-            n |= parts[k++] << j;
-            j += 24;
-            while (j > 7) {
-                emitted.push((n & 0x7f) | 0x80);
-                n >>= 7;
-                j -= 7;
-            }
-        }
-        n |= parts[m] << j;
-        do {
-            const byte = n & 0x7f;
-            n >>= 7;
-            if (n) {
-                emitted.push(byte | 0x80);
-            }
-            else {
-                emitted.push(byte);
-            }
-        } while (n);
-        if (neg) {
-            // Restore the original negative representation in the supplied buffer.
-            invert(arr, 8);
-        }
-        await this.appendRawBytes(Uint8Array.from(emitted));
-    }
 }

package/esm/serialization/tap_sync.d.ts

@@ -0,0 +1,240 @@
+import { TapBase } from "./tap.js";
+import type { ISyncReadable, ISyncWritable } from "./buffers/buffer_sync.js";
+/**
+ * Interface for synchronous readable tap operations in Avro serialization.
+ */
+export interface SyncReadableTapLike {
+    /** Returns whether the cursor is positioned within the buffer bounds. */
+    isValid(): boolean;
+    /** Returns whether more data can be read from the current position. */
+    canReadMore(): boolean;
+    /** Returns the buffer contents from the start up to the current cursor. */
+    getValue(): Uint8Array;
+    /** Reads the next byte as a boolean value and advances the cursor. */
+    readBoolean(): boolean;
+    /** Skips a boolean value by advancing the cursor by one byte. */
+    skipBoolean(): void;
+    /** Reads a variable-length zig-zag encoded 32-bit signed integer. */
+    readInt(): number;
+    /** Reads a variable-length zig-zag encoded 64-bit signed integer as bigint. */
+    readLong(): bigint;
+    /** Skips a zig-zag encoded 32-bit integer. */
+    skipInt(): void;
+    /** Skips a zig-zag encoded 64-bit integer. */
+    skipLong(): void;
+    /** Reads a 32-bit little-endian floating point number. */
+    readFloat(): number;
+    /** Skips a 32-bit floating point value by advancing four bytes. */
+    skipFloat(): void;
+    /** Reads a 64-bit little-endian floating point number. */
+    readDouble(): number;
+    /** Skips a 64-bit floating point value by advancing eight bytes. */
+    skipDouble(): void;
+    /** Reads a fixed-length byte sequence. */
+    readFixed(len: number): Uint8Array;
+    /** Skips a fixed-length byte sequence. */
+    skipFixed(len: number): void;
+    /** Reads a length-prefixed byte sequence. */
+    readBytes(): Uint8Array;
+    /** Skips a length-prefixed byte sequence. */
+    skipBytes(): void;
+    /** Reads a length-prefixed UTF-8 string. */
+    readString(): string;
+    /** Skips a length-prefixed UTF-8 string. */
+    skipString(): void;
+    /** Compares boolean values from this tap and another. */
+    matchBoolean(tap: SyncReadableTapLike): number;
+    /** Compares 32-bit integer values from this tap and another. */
+    matchInt(tap: SyncReadableTapLike): number;
+    /** Compares 64-bit integer values from this tap and another. */
+    matchLong(tap: SyncReadableTapLike): number;
+    /** Compares 32-bit float values from this tap and another. */
+    matchFloat(tap: SyncReadableTapLike): number;
+    /** Compares 64-bit double values from this tap and another. */
+    matchDouble(tap: SyncReadableTapLike): number;
+    /** Compares fixed-length byte sequences from this tap and another. */
+    matchFixed(tap: SyncReadableTapLike, len: number): number;
+    /** Compares length-prefixed byte sequences from this tap and another. */
+    matchBytes(tap: SyncReadableTapLike): number;
+    /** Compares length-prefixed strings from this tap and another. */
+    matchString(tap: SyncReadableTapLike): number;
+}
+/**
+ * Interface for synchronous writable tap operations in Avro serialization.
+ */
+export interface SyncWritableTapLike {
+    /** Returns whether the tap is valid for writing. */
+    isValid(): boolean;
+    /** Writes a boolean value as a single byte. */
+    writeBoolean(value: boolean): void;
+    /** Writes a zig-zag encoded 32-bit signed integer. */
+    writeInt(value: number): void;
+    /** Writes a zig-zag encoded 64-bit signed integer. */
+    writeLong(value: bigint): void;
+    /** Writes a 32-bit little-endian floating point number. */
+    writeFloat(value: number): void;
+    /** Writes a 64-bit little-endian floating point number. */
+    writeDouble(value: number): void;
+    /** Writes a fixed-length byte sequence. */
+    writeFixed(buf: Uint8Array): void;
+    /** Writes a length-prefixed byte sequence. */
+    writeBytes(buf: Uint8Array): void;
+    /** Writes a length-prefixed UTF-8 string. */
+    writeString(str: string): void;
+    /** Writes raw binary bytes without a length prefix. */
+    writeBinary(str: string, len: number): void;
+}
+/**
+ * Synchronous readable tap over an in-memory buffer.
+ * Mirrors ReadableTap but without Promises.
+ */
+export declare class SyncReadableTap extends TapBase implements SyncReadableTapLike {
+    private readonly buffer;
+    /**
+     * Creates a new SyncReadableTap.
+     * @param buf The buffer to read from, either an ArrayBuffer or ISyncReadable.
+     * @param pos The initial position in the buffer (default 0).
+     */
+    constructor(buf: ArrayBuffer | ISyncReadable, pos?: number);
+    /** Returns whether the cursor is positioned within the buffer bounds. */
+    isValid(): boolean;
+    /** Returns whether more data can be read from the current position. */
+    canReadMore(): boolean;
+    /** Returns the buffer contents from the start up to the current cursor. */
+    getValue(): Uint8Array;
+    /** Retrieves the byte at the specified position in the buffer. */
+    private getByteAt;
+    /** Reads the next byte as a boolean value and advances the cursor. */
+    readBoolean(): boolean;
+    /** Skips a boolean value by advancing the cursor by one byte. */
+    skipBoolean(): void;
+    /** Reads a variable-length zig-zag encoded 32-bit signed integer. */
+    readInt(): number;
+    /** Reads a variable-length zig-zag encoded 64-bit signed integer as bigint. */
+    readLong(): bigint;
+    /** Skips a zig-zag encoded 32-bit integer by delegating to skipLong. */
+    skipInt(): void;
+    /** Skips a zig-zag encoded 64-bit integer, advancing past continuation bytes. */
+    skipLong(): void;
+    /** Reads a 32-bit little-endian floating point number. */
+    readFloat(): number;
+    /** Skips a 32-bit floating point value by advancing four bytes. */
+    skipFloat(): void;
+    /** Reads a 64-bit little-endian floating point number. */
+    readDouble(): number;
+    /** Skips a 64-bit floating point value by advancing eight bytes. */
+    skipDouble(): void;
+    /** Reads a fixed-length byte sequence. */
+    readFixed(len: number): Uint8Array;
+    /** Skips a fixed-length byte sequence. */
+    skipFixed(len: number): void;
+    /** Reads a length-prefixed byte sequence. */
+    readBytes(): Uint8Array;
+    /** Skips a length-prefixed byte sequence. */
+    skipBytes(): void;
+    /** Reads a length-prefixed UTF-8 string. */
+    readString(): string;
+    /** Skips a length-prefixed UTF-8 string. */
+    skipString(): void;
+    /** Compares boolean values from this tap and another. */
+    matchBoolean(tap: SyncReadableTapLike): number;
+    /** Compares 32-bit integer values from this tap and another. */
+    matchInt(tap: SyncReadableTapLike): number;
+    /** Compares 64-bit integer values from this tap and another. */
+    matchLong(tap: SyncReadableTapLike): number;
+    /** Compares 32-bit float values from this tap and another. */
+    matchFloat(tap: SyncReadableTapLike): number;
+    /** Compares 64-bit double values from this tap and another. */
+    matchDouble(tap: SyncReadableTapLike): number;
+    /** Compares fixed-length byte sequences from this tap and another. */
+    matchFixed(tap: SyncReadableTapLike, len: number): number;
+    /** Compares length-prefixed byte sequences from this tap and another. */
+    matchBytes(tap: SyncReadableTapLike): number;
+    /** Compares length-prefixed strings from this tap and another. */
+    matchString(tap: SyncReadableTapLike): number;
+}
+/**
+ * Synchronous writable tap over an in-memory buffer (Uint8Array / ArrayBuffer).
+ * Mirrors WritableTap but without Promises.
+ */
+/**
+ * High-performance synchronous writable tap for Avro serialization.
+ *
+ * Key optimizations:
+ * - Buffer pool pattern: Pre-allocated static buffers eliminate GC pressure
+ * - Varint encoding: Direct buffer writing avoids intermediate allocations
+ * - ASCII string optimization: Fast path for ASCII strings, encodeInto() for Unicode
+ * - Static primitive buffers: Reuse buffers for booleans, floats, and doubles
+ */
+export declare class SyncWritableTap extends TapBase implements SyncWritableTapLike {
+    private readonly buffer;
+    private static readonly INT_MIN;
+    private static readonly INT_MAX;
+    private static readonly floatBuffer;
+    private static readonly floatView;
+    private static readonly float32Bytes;
+    private static readonly float64Bytes;
+    private static readonly trueByte;
+    private static readonly falseByte;
+    private static readonly varintBufferLong;
+    private static readonly varintBufferInt;
+    private static readonly stringBuffer;
+    private static encodedStringBuffer;
+    private static binaryBuffer;
+    /**
+     * Creates a new SyncWritableTap.
+     * @param buf The buffer to write to, either an ArrayBuffer or ISyncWritable.
+     * @param pos The initial position in the buffer (default 0).
+     */
+    constructor(buf: ArrayBuffer | ISyncWritable, pos?: number);
+    /** Returns whether the tap is valid for writing. */
+    isValid(): boolean;
+    /** Appends raw bytes to the buffer and advances the cursor. */
+    private appendRawBytes;
+    /** Writes a boolean value as a single byte. */
+    writeBoolean(value: boolean): void;
+    /**
+     * Writes a 32-bit integer using zigzag + varint encoding.
+     * Uses 32-bit math to avoid BigInt casts for performance.
+     */
+    writeInt(value: number): void;
+    /** Encodes a 32-bit integer using zigzag + varint encoding. */
+    private writeVarint32ZigZag;
+    /**
+     * Writes a 64-bit integer using zigzag + varint encoding.
+     *
+     * Optimizations:
+     * - Buffer pool: Uses pre-allocated varintBufferLong to avoid allocations
+     * - Direct buffer writing: Encodes into a shared buffer then appends a slice
+     *
+     * Performance impact: ~3x faster than original array-based approach
+     */
+    writeLong(value: bigint): void;
+    /** Writes a 32-bit little-endian floating point number. */
+    writeFloat(value: number): void;
+    /** Writes a 64-bit little-endian floating point number. */
+    writeDouble(value: number): void;
+    /** Writes a fixed-length byte sequence. */
+    writeFixed(buf: Uint8Array): void;
+    /** Writes a length-prefixed byte sequence. */
+    writeBytes(buf: Uint8Array): void;
+    /**
+     * Writes a UTF-8 encoded string with length prefix.
+     *
+     * Optimizations:
+     * - ASCII fast path: Direct charCodeAt() loop for ASCII strings (most common)
+     * - Unicode optimization: Uses TextEncoder.encodeInto() for zero-copy encoding
+     * - Buffer pool: Reuses stringBuffer to avoid allocations
+     * - Size estimation: Conservative UTF-8 size prediction (2x chars)
+     *
+     * Performance: ASCII strings ~800ns, Unicode strings ~1µs with encodeInto()
+     * Rationale: ASCII dominates real-world usage, Unicode needs zero-copy encoding
+     */
+    writeString(str: string): void;
+    /** Writes raw binary bytes without a length prefix. */
+    writeBinary(str: string, len: number): void;
+    /** Ensures the encoded string buffer is at least minSize bytes. */
+    private static ensureEncodedStringBuffer;
+    /** Ensures the binary buffer is at least size bytes. */
+    private static ensureBinaryBuffer;
+}