@sachitv/avro-typescript 0.4.1 → 0.5.0

package/esm/serialization/tap_sync.js

@@ -0,0 +1,545 @@
+import { bigIntToSafeNumber } from "./conversion.js";
+import { compareUint8Arrays } from "./compare_bytes.js";
+import { decode, encoder } from "./text_encoding.js";
+import { TapBase } from "./tap.js";
+import { ReadBufferError } from "./buffers/buffer_error.js";
+import { SyncInMemoryReadableBuffer, SyncInMemoryWritableBuffer, } from "./buffers/in_memory_buffer_sync.js";
+/**
+ * Type guard to check if an object implements ISyncReadable.
+ */
+function isISyncReadable(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        typeof obj.read === "function" &&
+        typeof obj.canReadMore === "function");
+}
+/**
+ * Type guard to check if an object implements ISyncWritable.
+ */
+function isISyncWritable(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        typeof obj.appendBytes === "function" &&
+        typeof obj.appendBytesFrom === "function" &&
+        typeof obj.isValid === "function" &&
+        typeof obj.canAppendMore === "function");
+}
+/**
+ * Synchronous readable tap over an in-memory buffer.
+ * Mirrors ReadableTap but without Promises.
+ */
+export class SyncReadableTap extends TapBase {
+    /**
+     * 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, pos = 0) {
+        super(pos);
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (buf instanceof ArrayBuffer) {
+            this.buffer = new SyncInMemoryReadableBuffer(buf);
+        }
+        else if (isISyncReadable(buf)) {
+            this.buffer = buf;
+        }
+        else {
+            throw new TypeError("SyncReadableTap requires an ArrayBuffer or ISyncReadable buffer.");
+        }
+    }
+    /** Returns whether the cursor is positioned within the buffer bounds. */
+    isValid() {
+        try {
+            this.buffer.read(this.pos, 0);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof ReadBufferError) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /** Returns whether more data can be read from the current position. */
+    canReadMore() {
+        return this.buffer.canReadMore(this.pos);
+    }
+    /** Returns the buffer contents from the start up to the current cursor. */
+    getValue() {
+        if (this.pos < 0) {
+            throw new ReadBufferError("Tap position is negative.", this.pos, 0, 0);
+        }
+        return this.buffer.read(0, this.pos);
+    }
+    /** Retrieves the byte at the specified position in the buffer. */
+    getByteAt(position) {
+        const result = this.buffer.read(position, 1);
+        return result[0];
+    }
+    /** Reads the next byte as a boolean value and advances the cursor. */
+    readBoolean() {
+        const value = this.getByteAt(this.pos);
+        this.pos += 1;
+        return !!value;
+    }
+    /** Skips a boolean value by advancing the cursor by one byte. */
+    skipBoolean() {
+        this.pos += 1;
+    }
+    /** Reads a variable-length zig-zag encoded 32-bit signed integer. */
+    readInt() {
+        return bigIntToSafeNumber(this.readLong(), "readInt value");
+    }
+    /** Reads a variable-length zig-zag encoded 64-bit signed integer as bigint. */
+    readLong() {
+        let pos = this.pos;
+        let shift = 0n;
+        let result = 0n;
+        let byte;
+        do {
+            byte = this.getByteAt(pos++);
+            result |= BigInt(byte & 0x7f) << shift;
+            shift += 7n;
+        } while ((byte & 0x80) !== 0 && shift < 70n);
+        while ((byte & 0x80) !== 0) {
+            byte = this.getByteAt(pos++);
+            result |= BigInt(byte & 0x7f) << shift;
+            shift += 7n;
+        }
+        this.pos = pos;
+        return (result >> 1n) ^ -(result & 1n);
+    }
+    /** Skips a zig-zag encoded 32-bit integer by delegating to skipLong. */
+    skipInt() {
+        this.skipLong();
+    }
+    /** Skips a zig-zag encoded 64-bit integer, advancing past continuation bytes. */
+    skipLong() {
+        let pos = this.pos;
+        while (this.getByteAt(pos++) & 0x80) {
+            /* no-op */
+        }
+        this.pos = pos;
+    }
+    /** Reads a 32-bit little-endian floating point number. */
+    readFloat() {
+        const pos = this.pos;
+        this.pos += 4;
+        const bytes = this.buffer.read(pos, 4);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return view.getFloat32(0, true);
+    }
+    /** Skips a 32-bit floating point value by advancing four bytes. */
+    skipFloat() {
+        this.pos += 4;
+    }
+    /** Reads a 64-bit little-endian floating point number. */
+    readDouble() {
+        const pos = this.pos;
+        this.pos += 8;
+        const bytes = this.buffer.read(pos, 8);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return view.getFloat64(0, true);
+    }
+    /** Skips a 64-bit floating point value by advancing eight bytes. */
+    skipDouble() {
+        this.pos += 8;
+    }
+    /** Reads a fixed-length byte sequence. */
+    readFixed(len) {
+        const pos = this.pos;
+        this.pos += len;
+        return this.buffer.read(pos, len);
+    }
+    /** Skips a fixed-length byte sequence. */
+    skipFixed(len) {
+        this.pos += len;
+    }
+    /** Reads a length-prefixed byte sequence. */
+    readBytes() {
+        const length = bigIntToSafeNumber(this.readLong(), "readBytes length");
+        return this.readFixed(length);
+    }
+    /** Skips a length-prefixed byte sequence. */
+    skipBytes() {
+        const len = bigIntToSafeNumber(this.readLong(), "skipBytes length");
+        this.pos += len;
+    }
+    /** Reads a length-prefixed UTF-8 string. */
+    readString() {
+        const len = bigIntToSafeNumber(this.readLong(), "readString length");
+        const bytes = this.readFixed(len);
+        return decode(bytes);
+    }
+    /** Skips a length-prefixed UTF-8 string. */
+    skipString() {
+        const len = bigIntToSafeNumber(this.readLong(), "skipString length");
+        this.pos += len;
+    }
+    /** Compares boolean values from this tap and another. */
+    matchBoolean(tap) {
+        const v1 = this.readBoolean();
+        const v2 = tap.readBoolean();
+        return Number(v1) - Number(v2);
+    }
+    /** Compares 32-bit integer values from this tap and another. */
+    matchInt(tap) {
+        return this.matchLong(tap);
+    }
+    /** Compares 64-bit integer values from this tap and another. */
+    matchLong(tap) {
+        const n1 = this.readLong();
+        const n2 = tap.readLong();
+        if (n1 === n2) {
+            return 0;
+        }
+        else if (n1 < n2) {
+            return -1;
+        }
+        else {
+            return 1;
+        }
+    }
+    /** Compares 32-bit float values from this tap and another. */
+    matchFloat(tap) {
+        const n1 = this.readFloat();
+        const n2 = tap.readFloat();
+        if (n1 === n2) {
+            return 0;
+        }
+        else if (n1 < n2) {
+            return -1;
+        }
+        else {
+            return 1;
+        }
+    }
+    /** Compares 64-bit double values from this tap and another. */
+    matchDouble(tap) {
+        const n1 = this.readDouble();
+        const n2 = tap.readDouble();
+        if (n1 === n2) {
+            return 0;
+        }
+        else if (n1 < n2) {
+            return -1;
+        }
+        else {
+            return 1;
+        }
+    }
+    /** Compares fixed-length byte sequences from this tap and another. */
+    matchFixed(tap, len) {
+        const f1 = this.readFixed(len);
+        const f2 = tap.readFixed(len);
+        return compareUint8Arrays(f1, f2);
+    }
+    /** Compares length-prefixed byte sequences from this tap and another. */
+    matchBytes(tap) {
+        return this.matchString(tap);
+    }
+    /** Compares length-prefixed strings from this tap and another. */
+    matchString(tap) {
+        const l1 = bigIntToSafeNumber(this.readLong(), "matchString length this");
+        const b1 = this.readFixed(l1);
+        const l2 = bigIntToSafeNumber(tap.readLong(), "matchString length tap");
+        const b2 = tap.readFixed(l2);
+        return compareUint8Arrays(b1, b2);
+    }
+}
+/**
+ * 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 class SyncWritableTap extends TapBase {
+    /**
+     * 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, pos = 0) {
+        super(pos);
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (buf instanceof ArrayBuffer) {
+            this.buffer = new SyncInMemoryWritableBuffer(buf, pos);
+        }
+        else if (isISyncWritable(buf)) {
+            this.buffer = buf;
+        }
+        else {
+            throw new TypeError("SyncWritableTap requires an ArrayBuffer or ISyncWritable buffer.");
+        }
+    }
+    /** Returns whether the tap is valid for writing. */
+    isValid() {
+        return this.buffer.isValid();
+    }
+    /** Appends raw bytes to the buffer and advances the cursor. */
+    appendRawBytes(bytes, offset = 0, length = bytes.length - offset) {
+        if (length <= 0)
+            return;
+        this.buffer.appendBytesFrom(bytes, offset, length);
+        this.pos += length;
+    }
+    /** Writes a boolean value as a single byte. */
+    writeBoolean(value) {
+        this.appendRawBytes(value ? SyncWritableTap.trueByte : SyncWritableTap.falseByte);
+    }
+    /**
+     * Writes a 32-bit integer using zigzag + varint encoding.
+     * Uses 32-bit math to avoid BigInt casts for performance.
+     */
+    writeInt(value) {
+        if (typeof value !== "number" ||
+            !Number.isInteger(value) ||
+            value < SyncWritableTap.INT_MIN ||
+            value > SyncWritableTap.INT_MAX) {
+            throw new RangeError(`Value ${value} out of range for Avro int (${SyncWritableTap.INT_MIN}..${SyncWritableTap.INT_MAX})`);
+        }
+        this.writeVarint32ZigZag(value);
+    }
+    /** Encodes a 32-bit integer using zigzag + varint encoding. */
+    writeVarint32ZigZag(value) {
+        // Zigzag encode to an unsigned 32-bit integer:
+        // (n << 1) ^ (n >> 31)
+        let n = ((value << 1) ^ (value >> 31)) >>> 0;
+        let i = 0;
+        const buf = SyncWritableTap.varintBufferInt;
+        while (n > 0x7f) {
+            buf[i++] = (n & 0x7f) | 0x80;
+            n >>>= 7;
+        }
+        buf[i++] = n;
+        this.appendRawBytes(buf, 0, i);
+    }
+    /**
+     * 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) {
+        let n = value;
+        if (n < 0n) {
+            n = ((-n) << 1n) - 1n;
+        }
+        else {
+            n <<= 1n;
+        }
+        // Fast varint encoding using pre-allocated buffer
+        let i = 0;
+        const buf = SyncWritableTap.varintBufferLong;
+        while (n >= 0x80n) {
+            buf[i++] = Number(n & 0x7fn) | 0x80;
+            n >>= 7n;
+        }
+        buf[i++] = Number(n);
+        this.appendRawBytes(buf, 0, i);
+    }
+    /** Writes a 32-bit little-endian floating point number. */
+    writeFloat(value) {
+        SyncWritableTap.floatView.setFloat32(0, value, true);
+        this.appendRawBytes(SyncWritableTap.float32Bytes);
+    }
+    /** Writes a 64-bit little-endian floating point number. */
+    writeDouble(value) {
+        SyncWritableTap.floatView.setFloat64(0, value, true);
+        this.appendRawBytes(SyncWritableTap.float64Bytes);
+    }
+    /** Writes a fixed-length byte sequence. */
+    writeFixed(buf) {
+        if (buf.length === 0)
+            return;
+        this.appendRawBytes(buf, 0, buf.length);
+    }
+    /** Writes a length-prefixed byte sequence. */
+    writeBytes(buf) {
+        const len = buf.length;
+        this.writeLong(BigInt(len));
+        this.writeFixed(buf);
+    }
+    /**
+     * 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) {
+        const strLen = str.length;
+        // Hybrid approach: ASCII fast path + encodeInto() for Unicode
+        if (strLen <= 1024) {
+            // Check if string is ASCII (single pass detection)
+            const buf = SyncWritableTap.stringBuffer;
+            let i = 0;
+            for (; i < strLen; i++) {
+                const code = str.charCodeAt(i);
+                if (code > 127) {
+                    break;
+                }
+                buf[i] = code;
+            }
+            if (i === strLen) {
+                // Fast ASCII path: direct charCodeAt() encoding
+                // Avoids TextEncoder overhead for common ASCII strings
+                // In this path, encoded length == strLen, so it can fit in an int.
+                this.writeInt(strLen);
+                if (strLen > 0) {
+                    this.appendRawBytes(buf, 0, strLen);
+                }
+                return;
+            }
+        }
+        // Fallback for large or complex strings
+        const estimatedSize = strLen * 3 + 4;
+        let encodedBuffer = SyncWritableTap.ensureEncodedStringBuffer(estimatedSize);
+        let result = encoder.encodeInto(str, encodedBuffer);
+        if (result.read !== strLen) {
+            encodedBuffer = SyncWritableTap.ensureEncodedStringBuffer(strLen * 4 + 8);
+            result = encoder.encodeInto(str, encodedBuffer);
+            if (result.read !== strLen) {
+                throw new Error("TextEncoder.encodeInto failed to consume the entire string.");
+            }
+        }
+        if (result.written > SyncWritableTap.INT_MAX) {
+            this.writeLong(BigInt(result.written));
+        }
+        else {
+            this.writeInt(result.written);
+        }
+        this.appendRawBytes(encodedBuffer, 0, result.written);
+    }
+    /** Writes raw binary bytes without a length prefix. */
+    writeBinary(str, len) {
+        if (len <= 0)
+            return;
+        const bytes = SyncWritableTap.ensureBinaryBuffer(len);
+        for (let i = 0; i < len; i++) {
+            bytes[i] = str.charCodeAt(i) & 0xff;
+        }
+        this.appendRawBytes(bytes, 0, len);
+    }
+    /** Ensures the encoded string buffer is at least minSize bytes. */
+    static ensureEncodedStringBuffer(minSize) {
+        if (SyncWritableTap.encodedStringBuffer.length < minSize) {
+            SyncWritableTap.encodedStringBuffer = new Uint8Array(minSize);
+        }
+        return SyncWritableTap.encodedStringBuffer;
+    }
+    /** Ensures the binary buffer is at least size bytes. */
+    static ensureBinaryBuffer(size) {
+        if (SyncWritableTap.binaryBuffer.length < size) {
+            SyncWritableTap.binaryBuffer = new Uint8Array(size);
+        }
+        return SyncWritableTap.binaryBuffer;
+    }
+}
+Object.defineProperty(SyncWritableTap, "INT_MIN", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: -2147483648
+});
+Object.defineProperty(SyncWritableTap, "INT_MAX", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 2147483647
+});
+// Buffer pool optimization: Pre-allocated static buffers to avoid per-operation allocations
+// Reduces GC pressure and improves performance for hot serialization paths
+Object.defineProperty(SyncWritableTap, "floatBuffer", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new ArrayBuffer(8)
+});
+Object.defineProperty(SyncWritableTap, "floatView", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new DataView(SyncWritableTap.floatBuffer)
+});
+Object.defineProperty(SyncWritableTap, "float32Bytes", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(SyncWritableTap.floatBuffer, 0, 4)
+});
+Object.defineProperty(SyncWritableTap, "float64Bytes", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(SyncWritableTap.floatBuffer, 0, 8)
+});
+Object.defineProperty(SyncWritableTap, "trueByte", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([1])
+});
+Object.defineProperty(SyncWritableTap, "falseByte", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array([0])
+});
+Object.defineProperty(SyncWritableTap, "varintBufferLong", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(11)
+}); // Max 11 bytes for 64-bit long (2^70 needs 11 bytes)
+Object.defineProperty(SyncWritableTap, "varintBufferInt", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(5)
+}); // Max 5 bytes for zigzag-encoded int32
+// String buffer pool: Pre-allocated buffer for ASCII string encoding
+// Avoids allocations for common ASCII strings up to 1024 characters
+Object.defineProperty(SyncWritableTap, "stringBuffer", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(1024)
+});
+Object.defineProperty(SyncWritableTap, "encodedStringBuffer", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(0)
+});
+Object.defineProperty(SyncWritableTap, "binaryBuffer", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: new Uint8Array(0)
+});

package/esm/serialization/text_encoding.d.ts

@@ -1,9 +1,25 @@
+/**
+ * Text encoding utilities with performance optimizations.
+ *
+ * Optimizations:
+ * - Export encoder for direct encodeInto() access (browser equivalent of utf8Write)
+ * - encodeInto() provides zero-copy UTF-8 encoding for modern browsers
+ * - Used in writeString() for Unicode string optimization
+ */
+export declare const encoder: TextEncoder;
 /**
  * Encodes a string into a Uint8Array using UTF-8 encoding.
  * @param input The string to encode.
  * @returns A Uint8Array representing the encoded string.
  */
 export declare const encode: (input: string) => Uint8Array;
+/**
+ * Returns the number of bytes needed to encode a string as UTF-8.
+ *
+ * This is equivalent to `encode(input).length` but avoids allocating a
+ * `Uint8Array`.
+ */
+export declare function utf8ByteLength(input: string): number;
 /**
  * Decodes a Uint8Array into a string using UTF-8 encoding.
  * @param bytes The Uint8Array to decode.

package/esm/serialization/text_encoding.js

@@ -1,4 +1,12 @@
-const encoder = new TextEncoder();
+/**
+ * Text encoding utilities with performance optimizations.
+ *
+ * Optimizations:
+ * - Export encoder for direct encodeInto() access (browser equivalent of utf8Write)
+ * - encodeInto() provides zero-copy UTF-8 encoding for modern browsers
+ * - Used in writeString() for Unicode string optimization
+ */
+export const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 /**
  * Encodes a string into a Uint8Array using UTF-8 encoding.
@@ -6,6 +14,45 @@ const decoder = new TextDecoder();
  * @returns A Uint8Array representing the encoded string.
  */
 export const encode = (input) => encoder.encode(input);
+/**
+ * Returns the number of bytes needed to encode a string as UTF-8.
+ *
+ * This is equivalent to `encode(input).length` but avoids allocating a
+ * `Uint8Array`.
+ */
+export function utf8ByteLength(input) {
+    let length = 0;
+    for (let index = 0; index < input.length; index++) {
+        const codeUnit = input.charCodeAt(index);
+        if (codeUnit < 0x80) {
+            length += 1;
+            continue;
+        }
+        if (codeUnit < 0x800) {
+            length += 2;
+            continue;
+        }
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const nextCodeUnit = input.charCodeAt(index + 1);
+            if (nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff) {
+                // Valid surrogate pair => code point >= 0x10000.
+                length += 4;
+                index++;
+                continue;
+            }
+            // Unpaired high surrogate; TextEncoder encodes this as U+FFFD.
+            length += 3;
+            continue;
+        }
+        if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            // Unpaired low surrogate; TextEncoder encodes this as U+FFFD.
+            length += 3;
+            continue;
+        }
+        length += 3;
+    }
+    return length;
+}
 /**
  * Decodes a Uint8Array into a string using UTF-8 encoding.
  * @param bytes The Uint8Array to decode.

package/esm/type/create_type.d.ts

@@ -1,3 +1,4 @@
+import { type RecordWriterStrategy } from "../schemas/complex/record_type.js";
 import { Type } from "../schemas/type.js";
 /**
  * Represents an Avro schema definition.
@@ -47,6 +48,25 @@ export interface CreateTypeOptions {
      * Registry of shared named types.
      */
     registry?: Map<string, Type>;
+    /**
+     * Whether to validate values during serialization writes.
+     *
+     * When set to `false`, types may skip runtime type/range checks on hot write
+     * paths for performance. This is unsafe for untrusted input and should only
+     * be used when values are already known to match the schema.
+     */
+    validate?: boolean;
+    /**
+     * Optional writer strategy for record types.
+     *
+     * Controls how record field writers are compiled:
+     * - `CompiledWriterStrategy` (default): Inlines primitive tap methods for performance.
+     * - `InterpretedWriterStrategy`: Delegates to type.write() for simplicity.
+     *
+     * Custom strategies can be provided for instrumentation, debugging, or
+     * alternative compilation approaches.
+     */
+    writerStrategy?: RecordWriterStrategy;
 }
 /**
  * Constructs an Avro {@link Type} from a schema definition.