@sachitv/avro-typescript 0.4.0

package/esm/serialization/tap.js

@@ -0,0 +1,605 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+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 { InMemoryReadableBuffer, InMemoryWritableBuffer, } from "./buffers/in_memory_buffer.js";
+function assertValidPosition(pos) {
+    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.");
+    }
+}
+function isIReadableBuffer(value) {
+    return typeof value === "object" && value !== null &&
+        typeof value.read === "function" &&
+        typeof value.canReadMore === "function";
+}
+function isIWritable(value) {
+    return typeof value === "object" && value !== null &&
+        typeof value.appendBytes === "function" &&
+        typeof value.isValid === "function";
+}
+/** Abstract base class for tap implementations that manage buffer position. */
+export class TapBase {
+    /** Initializes the tap with the given position. */
+    constructor(pos) {
+        /** The current position in the buffer. */
+        Object.defineProperty(this, "pos", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.pos = pos;
+    }
+    /**
+     * Returns the current cursor position within the buffer.
+     */
+    getPos() {
+        return this.pos;
+    }
+    /**
+     * Resets the cursor to the beginning of the buffer.
+     */
+    _testOnlyResetPos() {
+        this.pos = 0;
+    }
+}
+/**
+ * Binary tap that exposes Avro-compatible read helpers on top of a readable buffer.
+ */
+export class ReadableTap extends TapBase {
+    /** Creates a new ReadableTap with the given buffer and initial position. */
+    constructor(buf, pos = 0) {
+        assertValidPosition(pos);
+        let buffer;
+        let lengthHint;
+        if (buf instanceof ArrayBuffer) {
+            buffer = new InMemoryReadableBuffer(buf);
+            lengthHint = buf.byteLength;
+        }
+        else if (isIReadableBuffer(buf)) {
+            buffer = buf;
+        }
+        else {
+            throw new TypeError("ReadableTap requires an ArrayBuffer or IReadableBuffer.");
+        }
+        super(pos);
+        /** The readable buffer backing this tap. */
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        _ReadableTap_lengthHint.set(this, void 0);
+        this.buffer = buffer;
+        __classPrivateFieldSet(this, _ReadableTap_lengthHint, lengthHint, "f");
+    }
+    /**
+     * Returns whether the cursor is positioned within the buffer bounds.
+     */
+    async isValid() {
+        try {
+            const probe = await this.buffer.read(this.pos, 0);
+            return probe !== undefined;
+        }
+        catch (err) {
+            if (err instanceof RangeError) {
+                return false;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Returns whether more data can be read from the current position without advancing the cursor.
+     */
+    async canReadMore() {
+        return await this.buffer.canReadMore(this.pos);
+    }
+    /**
+     * Returns a defensive copy of the current buffer for testing purposes.
+     */
+    async _testOnlyBuf() {
+        const readLength = __classPrivateFieldGet(this, _ReadableTap_lengthHint, "f") ?? this.pos;
+        if (readLength <= 0) {
+            return new Uint8Array();
+        }
+        const bytes = await this.buffer.read(0, readLength);
+        if (bytes) {
+            return bytes.slice();
+        }
+        else {
+            return new Uint8Array();
+        }
+    }
+    /**
+     * Returns the buffer contents from the start up to the current cursor.
+     * @throws RangeError 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;
+    }
+    /** 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];
+    }
+    /**
+     * Reads the next byte as a boolean value and advances the cursor by one byte.
+     */
+    async readBoolean() {
+        const value = await this.getByteAt(this.pos);
+        this.pos += 1;
+        return !!value;
+    }
+    /**
+     * Skips a boolean value by advancing the cursor by one byte.
+     */
+    skipBoolean() {
+        this.pos++;
+    }
+    /**
+     * Reads a variable-length zig-zag encoded 32-bit signed integer.
+     */
+    async readInt() {
+        return bigIntToSafeNumber(await this.readLong(), "readInt value");
+    }
+    /**
+     * Reads a variable-length zig-zag encoded 64-bit signed integer as bigint.
+     */
+    async readLong() {
+        let pos = this.pos;
+        let shift = 0n;
+        let result = 0n;
+        let byte;
+        do {
+            byte = await this.getByteAt(pos++);
+            result |= BigInt(byte & 0x7f) << shift;
+            shift += 7n;
+        } while ((byte & 0x80) !== 0 && shift < 70n);
+        while ((byte & 0x80) !== 0) {
+            byte = await 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`.
+     */
+    async skipInt() {
+        await this.skipLong();
+    }
+    /**
+     * Skips a zig-zag encoded 64-bit integer, advancing past continuation bytes.
+     */
+    async skipLong() {
+        let pos = this.pos;
+        while ((await this.getByteAt(pos++)) & 0x80) {
+            /* no-op */
+        }
+        this.pos = pos;
+    }
+    /**
+     * Reads a 32-bit little-endian floating point number.
+     * @throws RangeError 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);
+    }
+    /**
+     * Skips a 32-bit floating point value by advancing four bytes.
+     */
+    skipFloat() {
+        this.pos += 4;
+    }
+    /**
+     * Reads a 64-bit little-endian floating point number.
+     * @throws RangeError 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);
+    }
+    /**
+     * Skips a 64-bit floating point value by advancing eight bytes.
+     */
+    skipDouble() {
+        this.pos += 8;
+    }
+    /**
+     * 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.
+     */
+    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;
+    }
+    /**
+     * Skips a fixed-length byte sequence.
+     * @param len Number of bytes to skip.
+     */
+    skipFixed(len) {
+        this.pos += len;
+    }
+    /**
+     * Reads a length-prefixed byte sequence.
+     * @throws RangeError if insufficient data remains.
+     */
+    async readBytes() {
+        const length = bigIntToSafeNumber(await this.readLong(), "readBytes length");
+        return await this.readFixed(length);
+    }
+    /**
+     * Skips a length-prefixed byte sequence.
+     */
+    async skipBytes() {
+        const len = bigIntToSafeNumber(await this.readLong(), "skipBytes length");
+        this.pos += len;
+    }
+    /**
+     * Skips a length-prefixed UTF-8 string.
+     */
+    async skipString() {
+        const len = bigIntToSafeNumber(await this.readLong(), "skipString length");
+        this.pos += len;
+    }
+    /**
+     * Reads a length-prefixed UTF-8 string.
+     * @throws RangeError when the buffer is exhausted prematurely.
+     */
+    async readString() {
+        const len = bigIntToSafeNumber(await this.readLong(), "readString length");
+        const bytes = await this.readFixed(len);
+        return decode(bytes);
+    }
+    /**
+     * Compares the next boolean value with the one from another tap.
+     * @param tap Tap to compare against; both cursors advance.
+     * @returns 0 when equal, negative when this tap's value is false and the other true, positive otherwise.
+     */
+    async matchBoolean(tap) {
+        const val1 = await this.readBoolean();
+        const val2 = await tap.readBoolean();
+        return Number(val1) - Number(val2);
+    }
+    /**
+     * Compares the next zig-zag encoded 32-bit integer with another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchInt(tap) {
+        return await this.matchLong(tap);
+    }
+    /**
+     * Compares the next zig-zag encoded 64-bit integer with another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchLong(tap) {
+        const n1 = await this.readLong();
+        const n2 = await tap.readLong();
+        return n1 === n2 ? 0 : (n1 < n2 ? -1 : 1);
+    }
+    /**
+     * Compares the next 32-bit float value with another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchFloat(tap) {
+        const n1 = await this.readFloat();
+        const n2 = await tap.readFloat();
+        return n1 === n2 ? 0 : (n1 < n2 ? -1 : 1);
+    }
+    /**
+     * Compares the next 64-bit float value with another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchDouble(tap) {
+        const n1 = await this.readDouble();
+        const n2 = await tap.readDouble();
+        return n1 === n2 ? 0 : (n1 < n2 ? -1 : 1);
+    }
+    /**
+     * Compares fixed-length byte sequences from this tap and another tap.
+     * @param tap Tap to compare against; both cursors advance by `len`.
+     * @param len Number of bytes to compare.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchFixed(tap, len) {
+        const fixed1 = await this.readFixed(len);
+        const fixed2 = await tap.readFixed(len);
+        return compareUint8Arrays(fixed1, fixed2);
+    }
+    /**
+     * Compares length-prefixed byte sequences from this tap and another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchBytes(tap) {
+        return await this.matchString(tap);
+    }
+    /**
+     * Compares length-prefixed UTF-8 strings read from this tap and another tap.
+     * @returns Comparison result using -1/0/1 semantics.
+     */
+    async matchString(tap) {
+        const l1 = bigIntToSafeNumber(await this.readLong(), "matchString length this");
+        const bytes1 = await this.readFixed(l1);
+        const l2 = bigIntToSafeNumber(await tap.readLong(), "matchString length tap");
+        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();
+/**
+ * Binary tap that exposes Avro-compatible write helpers on top of a writable buffer.
+ */
+export class WritableTap extends TapBase {
+    /**
+     * Creates a new WritableTap instance.
+     * @param buf The buffer to write to, either an ArrayBuffer or IWritableBuffer.
+     * @param pos The initial position in the buffer (default 0).
+     */
+    constructor(buf, pos = 0) {
+        assertValidPosition(pos);
+        let buffer;
+        if (buf instanceof ArrayBuffer) {
+            buffer = new InMemoryWritableBuffer(buf, pos);
+        }
+        else if (isIWritable(buf)) {
+            buffer = buf;
+        }
+        else {
+            throw new TypeError("WritableTap requires an ArrayBuffer or IWritableBuffer.");
+        }
+        super(pos);
+        /** The writable buffer backing this tap. */
+        Object.defineProperty(this, "buffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.buffer = buffer;
+    }
+    /**
+     * Appends raw bytes to the buffer and advances the cursor.
+     * @param bytes The bytes to append.
+     */
+    async appendRawBytes(bytes) {
+        if (bytes.length === 0) {
+            return;
+        }
+        this.pos += bytes.length;
+        await this.buffer.appendBytes(bytes);
+    }
+    /** Checks if the buffer is valid. */
+    async isValid() {
+        return await this.buffer.isValid();
+    }
+    /**
+     * Writes a boolean value as a single byte and advances the cursor.
+     * @param value Boolean value to write.
+     */
+    async writeBoolean(value) {
+        await this.appendRawBytes(Uint8Array.of(value ? 1 : 0));
+    }
+    /**
+     * Writes a zig-zag encoded 32-bit signed integer.
+     * @param n Integer value to write.
+     */
+    async writeInt(n) {
+        await this.writeLong(BigInt(n));
+    }
+    /**
+     * Writes a zig-zag encoded 64-bit signed integer.
+     * @param value BigInt value to write.
+     */
+    async writeLong(value) {
+        let n = value;
+        if (n < 0n) {
+            n = ((-n) << 1n) - 1n;
+        }
+        else {
+            n <<= 1n;
+        }
+        const bytes = [];
+        while (n >= 0x80n) {
+            bytes.push(Number(n & 0x7fn) | 0x80);
+            n >>= 7n;
+        }
+        bytes.push(Number(n));
+        await this.appendRawBytes(Uint8Array.from(bytes));
+    }
+    /**
+     * Writes a 32-bit little-endian floating point number.
+     * @param value Float to write.
+     */
+    async writeFloat(value) {
+        const buffer = new ArrayBuffer(4);
+        const view = new DataView(buffer);
+        view.setFloat32(0, value, true);
+        await this.appendRawBytes(new Uint8Array(buffer));
+    }
+    /**
+     * Writes a 64-bit little-endian floating point number.
+     * @param value Double precision value to write.
+     */
+    async writeDouble(value) {
+        const buffer = new ArrayBuffer(8);
+        const view = new DataView(buffer);
+        view.setFloat64(0, value, true);
+        await this.appendRawBytes(new Uint8Array(buffer));
+    }
+    /**
+     * 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) {
+            return;
+        }
+        await this.appendRawBytes(buf.slice(0, length));
+    }
+    /**
+     * Writes a length-prefixed byte sequence backed by the provided buffer.
+     * @param buf Bytes to write.
+     */
+    async writeBytes(buf) {
+        const len = buf.length;
+        await this.writeLong(BigInt(len));
+        await this.writeFixed(buf, len);
+    }
+    /**
+     * Writes a length-prefixed UTF-8 string.
+     * @param str String to encode and write.
+     */
+    async writeString(str) {
+        const encoded = encode(str);
+        const len = encoded.length;
+        await this.writeLong(BigInt(len));
+        await this.writeFixed(encoded, len);
+    }
+    /**
+     * Writes a binary string as raw bytes without a length prefix.
+     * @param str Source string containing binary data.
+     * @param len Number of bytes from the string to write.
+     */
+    async writeBinary(str, len) {
+        if (len <= 0) {
+            return;
+        }
+        const bytes = new Uint8Array(len);
+        for (let i = 0; i < len; i++) {
+            bytes[i] = str.charCodeAt(i) & 0xff;
+        }
+        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/text_encoding.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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;
+/**
+ * Decodes a Uint8Array into a string using UTF-8 encoding.
+ * @param bytes The Uint8Array to decode.
+ * @returns The decoded string.
+ */
+export declare const decode: (bytes: Uint8Array) => string;

package/esm/serialization/text_encoding.js

@@ -0,0 +1,14 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Encodes a string into a Uint8Array using UTF-8 encoding.
+ * @param input The string to encode.
+ * @returns A Uint8Array representing the encoded string.
+ */
+export const encode = (input) => encoder.encode(input);
+/**
+ * Decodes a Uint8Array into a string using UTF-8 encoding.
+ * @param bytes The Uint8Array to decode.
+ * @returns The decoded string.
+ */
+export const decode = (bytes) => decoder.decode(bytes);

package/esm/type/create_type.d.ts

@@ -0,0 +1,54 @@
+import { Type } from "../schemas/type.js";
+/**
+ * Represents an Avro schema definition.
+ * Can be a pre-constructed Type, a type name (string), a schema object,
+ * or an array representing a union.
+ */
+export type SchemaLike = Type | string | SchemaObject | SchemaLike[];
+/**
+ * Represents an Avro schema object, which defines the structure of data in Avro format.
+ * It can represent primitive types, complex types like records and arrays, or named types.
+ */
+export interface SchemaObject {
+    /** The type of the Avro schema, such as "record", "array", "enum", "fixed", or a primitive type like "string". */
+    type: unknown;
+    /** The name of the schema for named types like records, enums, and fixed types. */
+    name?: unknown;
+    /** The namespace for the schema, used to qualify named types and avoid naming conflicts. */
+    namespace?: unknown;
+    /** Alternative names (aliases) for the schema, allowing backward compatibility or multiple references. */
+    aliases?: unknown;
+    /** The fields of a record schema, an array of field definitions each specifying name, type, and optional default. */
+    fields?: unknown;
+    /** The symbols for an enum schema, an array of string values representing the possible enumeration values. */
+    symbols?: unknown;
+    /** The size in bytes for a fixed schema, specifying the exact length of the fixed-size data. */
+    size?: unknown;
+    /** The type of items in an array schema, defining the schema for each element in the array. */
+    items?: unknown;
+    /** The type of values in a map schema, defining the schema for the values associated with string keys. */
+    values?: unknown;
+    /** The default value for a field in a record or for an enum, used when the field is missing in the data. */
+    default?: unknown;
+    /** The logical type annotation, such as "date", "decimal", or "uuid", providing semantic meaning to the underlying type. */
+    logicalType?: unknown;
+    /** Allows additional arbitrary properties in the schema object for extensibility. */
+    [key: string]: unknown;
+}
+/**
+ * Options for creating an Avro type from a schema.
+ */
+export interface CreateTypeOptions {
+    /**
+     * Default namespace to use for named types.
+     */
+    namespace?: string;
+    /**
+     * Registry of shared named types.
+     */
+    registry?: Map<string, Type>;
+}
+/**
+ * Constructs an Avro {@link Type} from a schema definition.
+ */
+export declare function createType(schema: SchemaLike, options?: CreateTypeOptions): Type;