@sachitv/avro-typescript 0.4.2 → 0.5.0

package/esm/schemas/type.js

@@ -1,6 +1,103 @@
+import { WritableTap, } from "../serialization/tap.js";
+import { SyncWritableTap, } from "../serialization/tap_sync.js";
+import { CountingWritableTap } from "../serialization/counting_writable_tap.js";
+import { SyncCountingWritableTap } from "../serialization/counting_writable_tap_sync.js";
+import { throwInvalidError } from "./error.js";
 /**
  * Pure abstract base class for all Avro schema types.
  * Provides the common interface for serialization, deserialization, validation, and cloning.
  */
 export class Type {
+    /** Creates a new Type instance. */
+    constructor(validate = true) {
+        /** Controls whether write operations validate values before serialization. */
+        Object.defineProperty(this, "validateWrites", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.validateWrites = validate;
+    }
+    /**
+     * Serializes a value into an ArrayBuffer using the schema.
+     * @param value The value to serialize.
+     * @returns The serialized ArrayBuffer.
+     */
+    async toBuffer(value) {
+        if (this.validateWrites) {
+            this.check(value, throwInvalidError, []);
+        }
+        const sizeHint = this.byteLength(value);
+        if (sizeHint !== undefined) {
+            const buffer = new ArrayBuffer(assertValidSize(sizeHint));
+            const tap = new WritableTap(buffer);
+            await this.writeUnchecked(tap, value);
+            return buffer;
+        }
+        const countingTap = new CountingWritableTap();
+        await this.writeUnchecked(countingTap, value);
+        const buffer = new ArrayBuffer(countingTap.getPos());
+        const tap = new WritableTap(buffer);
+        await this.writeUnchecked(tap, value);
+        return buffer;
+    }
+    /**
+     * Writes a value to the tap. Must be implemented by subclasses.
+     * @param tap The tap to write to.
+     * @param value The value to write.
+     */
+    async write(tap, value) {
+        if (this.validateWrites) {
+            this.check(value, throwInvalidError, []);
+        }
+        await this.writeUnchecked(tap, value);
+    }
+    /**
+     * Serializes a value into an ArrayBuffer synchronously using the schema.
+     * @param value The value to serialize.
+     * @returns The serialized ArrayBuffer.
+     */
+    toSyncBuffer(value) {
+        if (this.validateWrites) {
+            this.check(value, throwInvalidError, []);
+        }
+        const sizeHint = this.byteLength(value);
+        if (sizeHint !== undefined) {
+            const buffer = new ArrayBuffer(assertValidSize(sizeHint));
+            const tap = new SyncWritableTap(buffer);
+            this.writeSyncUnchecked(tap, value);
+            return buffer;
+        }
+        const countingTap = new SyncCountingWritableTap();
+        this.writeSyncUnchecked(countingTap, value);
+        const buffer = new ArrayBuffer(countingTap.getPos());
+        const tap = new SyncWritableTap(buffer);
+        this.writeSyncUnchecked(tap, value);
+        return buffer;
+    }
+    /**
+     * Writes a value to the sync tap. Must be implemented by subclasses.
+     * @param tap The sync tap to write to.
+     * @param value The value to write.
+     */
+    writeSync(tap, value) {
+        if (this.validateWrites) {
+            this.check(value, throwInvalidError, []);
+        }
+        this.writeSyncUnchecked(tap, value);
+    }
+    /**
+     * Returns the encoded byte length for the value when it is cheap to compute.
+     * Override in types with fixed or easily derived sizes to skip counting taps.
+     */
+    byteLength(_value) {
+        return undefined;
+    }
+}
+function assertValidSize(size) {
+    if (!Number.isFinite(size) || !Number.isInteger(size) || size < 0) {
+        throw new RangeError(`Invalid byte length: ${size}`);
+    }
+    return size;
 }

package/esm/serialization/avro_file_parser_sync.d.ts

@@ -0,0 +1,34 @@
+import type { ParsedAvroHeader } from "./avro_file_parser.js";
+import type { ISyncReadable } from "./buffers/buffer_sync.js";
+import type { SyncDecoderRegistry } from "./decoders/decoder_sync.js";
+/**
+ * Options for configuring the synchronous Avro file parser.
+ */
+export interface SyncAvroFileParserOptions {
+    /** Optional reader schema used when resolving writer data to a different schema. */
+    readerSchema?: unknown;
+    /** Custom codec decoders. Cannot include "null" as it is built-in. */
+    decoders?: SyncDecoderRegistry;
+}
+/**
+ * Parser for Avro object container files that operates purely synchronously.
+ * It mirrors {@link AvroFileParser} but leverages {@link SyncReadableTap} and
+ * {@link ISyncReadable} buffers so callers can avoid async control flow.
+ */
+export declare class SyncAvroFileParser {
+    #private;
+    /**
+     * Creates a new synchronous Avro file parser.
+     * @param buffer The readable buffer containing the Avro container.
+     * @param options Configuration options including reader schema and decoders.
+     */
+    constructor(buffer: ISyncReadable, options?: SyncAvroFileParserOptions);
+    /**
+     * Returns the parsed Avro header. Header parsing happens at most once.
+     */
+    getHeader(): ParsedAvroHeader;
+    /**
+     * Iterates synchronously over every record contained in the Avro file.
+     */
+    iterRecords(): IterableIterator<unknown>;
+}

package/esm/serialization/avro_file_parser_sync.js

@@ -0,0 +1,160 @@
+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 _SyncAvroFileParser_instances, _SyncAvroFileParser_buffer, _SyncAvroFileParser_header, _SyncAvroFileParser_headerTap, _SyncAvroFileParser_readerSchema, _SyncAvroFileParser_readerType, _SyncAvroFileParser_resolver, _SyncAvroFileParser_customDecoders, _SyncAvroFileParser_builtInDecoders, _SyncAvroFileParser_parseHeader, _SyncAvroFileParser_getResolver, _SyncAvroFileParser_createReaderType, _SyncAvroFileParser_getDecoder;
+import { createType } from "../type/create_type.js";
+import { Type } from "../schemas/type.js";
+import { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES } from "./avro_constants.js";
+import { NullDecoderSync } from "./decoders/decoder_null_sync.js";
+import { SyncReadableTap } from "./tap_sync.js";
+/**
+ * Parser for Avro object container files that operates purely synchronously.
+ * It mirrors {@link AvroFileParser} but leverages {@link SyncReadableTap} and
+ * {@link ISyncReadable} buffers so callers can avoid async control flow.
+ */
+export class SyncAvroFileParser {
+    /**
+     * Creates a new synchronous Avro file parser.
+     * @param buffer The readable buffer containing the Avro container.
+     * @param options Configuration options including reader schema and decoders.
+     */
+    constructor(buffer, options) {
+        _SyncAvroFileParser_instances.add(this);
+        _SyncAvroFileParser_buffer.set(this, void 0);
+        _SyncAvroFileParser_header.set(this, void 0);
+        _SyncAvroFileParser_headerTap.set(this, void 0);
+        _SyncAvroFileParser_readerSchema.set(this, void 0);
+        _SyncAvroFileParser_readerType.set(this, void 0);
+        _SyncAvroFileParser_resolver.set(this, void 0);
+        _SyncAvroFileParser_customDecoders.set(this, void 0);
+        _SyncAvroFileParser_builtInDecoders.set(this, void 0);
+        __classPrivateFieldSet(this, _SyncAvroFileParser_buffer, buffer, "f");
+        __classPrivateFieldSet(this, _SyncAvroFileParser_readerSchema, options?.readerSchema, "f");
+        __classPrivateFieldSet(this, _SyncAvroFileParser_builtInDecoders, {
+            "null": new NullDecoderSync(),
+        }, "f");
+        const custom = options?.decoders ?? {};
+        for (const codec of Object.keys(custom)) {
+            if (codec in __classPrivateFieldGet(this, _SyncAvroFileParser_builtInDecoders, "f")) {
+                throw new Error(`Cannot override built-in decoder for codec: ${codec}`);
+            }
+        }
+        __classPrivateFieldSet(this, _SyncAvroFileParser_customDecoders, { ...custom }, "f");
+    }
+    /**
+     * Returns the parsed Avro header. Header parsing happens at most once.
+     */
+    getHeader() {
+        const header = __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_parseHeader).call(this);
+        return {
+            magic: header.magic,
+            meta: header.meta,
+            sync: header.sync,
+        };
+    }
+    /**
+     * Iterates synchronously over every record contained in the Avro file.
+     */
+    *iterRecords() {
+        const header = __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_parseHeader).call(this);
+        const { schemaType, meta } = header;
+        const resolver = __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_getResolver).call(this, schemaType);
+        const codecBytes = meta.get("avro.codec");
+        const codec = (() => {
+            if (codecBytes === undefined) {
+                return "null";
+            }
+            const decoded = new TextDecoder().decode(codecBytes);
+            return decoded.length === 0 ? "null" : decoded;
+        })();
+        const decoder = __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_getDecoder).call(this, codec);
+        const tap = __classPrivateFieldGet(this, _SyncAvroFileParser_headerTap, "f");
+        while (tap.canReadMore()) {
+            const block = BLOCK_TYPE.readSync(tap);
+            const decompressed = decoder.decode(block.data);
+            const arrayBuffer = new ArrayBuffer(decompressed.length);
+            new Uint8Array(arrayBuffer).set(decompressed);
+            const recordTap = new SyncReadableTap(arrayBuffer);
+            for (let i = 0n; i < block.count; i += 1n) {
+                const value = resolver
+                    ? resolver.readSync(recordTap)
+                    : schemaType.readSync(recordTap);
+                yield value;
+            }
+        }
+    }
+}
+_SyncAvroFileParser_buffer = new WeakMap(), _SyncAvroFileParser_header = new WeakMap(), _SyncAvroFileParser_headerTap = new WeakMap(), _SyncAvroFileParser_readerSchema = new WeakMap(), _SyncAvroFileParser_readerType = new WeakMap(), _SyncAvroFileParser_resolver = new WeakMap(), _SyncAvroFileParser_customDecoders = new WeakMap(), _SyncAvroFileParser_builtInDecoders = new WeakMap(), _SyncAvroFileParser_instances = new WeakSet(), _SyncAvroFileParser_parseHeader = function _SyncAvroFileParser_parseHeader() {
+    if (__classPrivateFieldGet(this, _SyncAvroFileParser_header, "f")) {
+        return __classPrivateFieldGet(this, _SyncAvroFileParser_header, "f");
+    }
+    const tap = new SyncReadableTap(__classPrivateFieldGet(this, _SyncAvroFileParser_buffer, "f"));
+    const header = HEADER_TYPE.readSync(tap);
+    const magic = header.magic;
+    for (let i = 0; i < MAGIC_BYTES.length; i++) {
+        if (magic[i] !== MAGIC_BYTES[i]) {
+            throw new Error("Invalid AVRO file: incorrect magic bytes");
+        }
+    }
+    const meta = header.meta;
+    const schemaJson = meta.get("avro.schema");
+    if (!schemaJson) {
+        throw new Error("AVRO schema not found in metadata");
+    }
+    const schemaStr = new TextDecoder().decode(schemaJson);
+    const schemaType = createType(JSON.parse(schemaStr));
+    const codec = meta.get("avro.codec");
+    if (codec && codec.length > 0) {
+        const codecStr = new TextDecoder().decode(codec);
+        __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_getDecoder).call(this, codecStr);
+    }
+    const sync = header.sync;
+    __classPrivateFieldSet(this, _SyncAvroFileParser_header, {
+        magic,
+        meta,
+        sync,
+        schemaType,
+    }, "f");
+    __classPrivateFieldSet(this, _SyncAvroFileParser_headerTap, tap, "f");
+    return __classPrivateFieldGet(this, _SyncAvroFileParser_header, "f");
+}, _SyncAvroFileParser_getResolver = function _SyncAvroFileParser_getResolver(writerType) {
+    if (__classPrivateFieldGet(this, _SyncAvroFileParser_readerSchema, "f") === undefined || __classPrivateFieldGet(this, _SyncAvroFileParser_readerSchema, "f") === null) {
+        return undefined;
+    }
+    if (!__classPrivateFieldGet(this, _SyncAvroFileParser_readerType, "f")) {
+        __classPrivateFieldSet(this, _SyncAvroFileParser_readerType, __classPrivateFieldGet(this, _SyncAvroFileParser_instances, "m", _SyncAvroFileParser_createReaderType).call(this, __classPrivateFieldGet(this, _SyncAvroFileParser_readerSchema, "f")), "f");
+    }
+    if (!__classPrivateFieldGet(this, _SyncAvroFileParser_resolver, "f")) {
+        __classPrivateFieldSet(this, _SyncAvroFileParser_resolver, __classPrivateFieldGet(this, _SyncAvroFileParser_readerType, "f").createResolver(writerType), "f");
+    }
+    return __classPrivateFieldGet(this, _SyncAvroFileParser_resolver, "f");
+}, _SyncAvroFileParser_createReaderType = function _SyncAvroFileParser_createReaderType(schema) {
+    if (schema instanceof Type) {
+        return schema;
+    }
+    if (typeof schema === "string") {
+        const trimmed = schema.trim();
+        if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+            const parsed = JSON.parse(trimmed);
+            return createType(parsed);
+        }
+        return createType(schema);
+    }
+    return createType(schema);
+}, _SyncAvroFileParser_getDecoder = function _SyncAvroFileParser_getDecoder(codec) {
+    if (codec in __classPrivateFieldGet(this, _SyncAvroFileParser_builtInDecoders, "f")) {
+        return __classPrivateFieldGet(this, _SyncAvroFileParser_builtInDecoders, "f")[codec];
+    }
+    if (codec in __classPrivateFieldGet(this, _SyncAvroFileParser_customDecoders, "f")) {
+        return __classPrivateFieldGet(this, _SyncAvroFileParser_customDecoders, "f")[codec];
+    }
+    throw new Error(`Unsupported codec: ${codec}. Provide a custom decoder.`);
+};

package/esm/serialization/avro_file_writer_sync.d.ts

@@ -0,0 +1,47 @@
+import { type SchemaLike } from "../type/create_type.js";
+import type { MetadataInit } from "./avro_file_writer.js";
+import type { ISyncWritable } from "./buffers/buffer_sync.js";
+import type { SyncEncoderRegistry } from "./encoders/encoder_sync.js";
+/**
+ * Options accepted by {@link SyncAvroFileWriter}.
+ */
+export interface SyncAvroWriterOptions {
+    /** The Avro schema for records to be written. */
+    schema: SchemaLike;
+    /** The compression codec to use (default: "null"). */
+    codec?: string;
+    /** Target block size in bytes before flushing (default: 64000). */
+    blockSize?: number;
+    /** Custom 16-byte sync marker (defaults to random). */
+    syncMarker?: Uint8Array;
+    /** Additional user metadata to include in the header. */
+    metadata?: MetadataInit;
+    /** Custom codec encoders. */
+    encoders?: SyncEncoderRegistry;
+}
+/**
+ * Fully synchronous Avro container file writer.
+ * Mirrors {@link AvroFileWriter} but relies on {@link SyncWritableTap} so it
+ * can run where async primitives are unavailable.
+ */
+export declare class SyncAvroFileWriter {
+    #private;
+    /**
+     * Creates a new synchronous Avro file writer.
+     * @param buffer The writable buffer to write the Avro container to.
+     * @param options Configuration options including schema and codec.
+     */
+    constructor(buffer: ISyncWritable, options: SyncAvroWriterOptions);
+    /**
+     * Appends a record to the pending block, flushing when the block size is met.
+     */
+    append(record: unknown): void;
+    /**
+     * Flushes any pending data and prevents further writes.
+     */
+    close(): void;
+    /**
+     * Forces pending data into a block immediately.
+     */
+    flushBlock(): void;
+}

package/esm/serialization/avro_file_writer_sync.js

@@ -0,0 +1,211 @@
+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 _SyncAvroFileWriter_instances, _SyncAvroFileWriter_tap, _SyncAvroFileWriter_schemaType, _SyncAvroFileWriter_codec, _SyncAvroFileWriter_encoder, _SyncAvroFileWriter_blockSize, _SyncAvroFileWriter_syncMarker, _SyncAvroFileWriter_metadata, _SyncAvroFileWriter_pendingRecords, _SyncAvroFileWriter_pendingBytes, _SyncAvroFileWriter_pendingCount, _SyncAvroFileWriter_headerWritten, _SyncAvroFileWriter_closed, _SyncAvroFileWriter_builtInEncoders, _SyncAvroFileWriter_customEncoders, _SyncAvroFileWriter_ensureOpen, _SyncAvroFileWriter_ensureHeaderWritten, _SyncAvroFileWriter_writeHeader, _SyncAvroFileWriter_validateBlockSize, _SyncAvroFileWriter_initializeSyncMarker, _SyncAvroFileWriter_validateCustomEncoders, _SyncAvroFileWriter_resolveEncoder, _SyncAvroFileWriter_buildMetadata, _SyncAvroFileWriter_assertMetadataKey, _SyncAvroFileWriter_encodeRecord, _SyncAvroFileWriter_combinePending;
+import { createType } from "../type/create_type.js";
+import { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES } from "./avro_constants.js";
+import { NullEncoderSync } from "./encoders/encoder_null_sync.js";
+import { encode as encodeString } from "./text_encoding.js";
+import { SyncWritableTap } from "./tap_sync.js";
+const DEFAULT_BLOCK_SIZE_BYTES = 64000;
+const SYNC_MARKER_SIZE = 16;
+const RESERVED_METADATA_KEYS = new Set(["avro.schema", "avro.codec"]);
+/**
+ * Fully synchronous Avro container file writer.
+ * Mirrors {@link AvroFileWriter} but relies on {@link SyncWritableTap} so it
+ * can run where async primitives are unavailable.
+ */
+export class SyncAvroFileWriter {
+    /**
+     * Creates a new synchronous Avro file writer.
+     * @param buffer The writable buffer to write the Avro container to.
+     * @param options Configuration options including schema and codec.
+     */
+    constructor(buffer, options) {
+        _SyncAvroFileWriter_instances.add(this);
+        _SyncAvroFileWriter_tap.set(this, void 0);
+        _SyncAvroFileWriter_schemaType.set(this, void 0);
+        _SyncAvroFileWriter_codec.set(this, void 0);
+        _SyncAvroFileWriter_encoder.set(this, void 0);
+        _SyncAvroFileWriter_blockSize.set(this, void 0);
+        _SyncAvroFileWriter_syncMarker.set(this, void 0);
+        _SyncAvroFileWriter_metadata.set(this, void 0);
+        _SyncAvroFileWriter_pendingRecords.set(this, []);
+        _SyncAvroFileWriter_pendingBytes.set(this, 0);
+        _SyncAvroFileWriter_pendingCount.set(this, 0);
+        _SyncAvroFileWriter_headerWritten.set(this, false);
+        _SyncAvroFileWriter_closed.set(this, false);
+        _SyncAvroFileWriter_builtInEncoders.set(this, void 0);
+        _SyncAvroFileWriter_customEncoders.set(this, void 0);
+        if (!options || !options.schema) {
+            throw new Error("Avro writer requires a schema.");
+        }
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_tap, new SyncWritableTap(buffer), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_schemaType, createType(options.schema), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_codec, options.codec ?? "null", "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_blockSize, __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_validateBlockSize).call(this, options.blockSize), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_syncMarker, __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_initializeSyncMarker).call(this, options.syncMarker), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_builtInEncoders, {
+            "null": new NullEncoderSync(),
+        }, "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_customEncoders, __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_validateCustomEncoders).call(this, options.encoders), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_encoder, __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_resolveEncoder).call(this, __classPrivateFieldGet(this, _SyncAvroFileWriter_codec, "f")), "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_metadata, __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_buildMetadata).call(this, options.metadata), "f");
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_metadata, "f").set("avro.schema", encodeString(JSON.stringify(__classPrivateFieldGet(this, _SyncAvroFileWriter_schemaType, "f").toJSON())));
+        if (__classPrivateFieldGet(this, _SyncAvroFileWriter_codec, "f") !== "null") {
+            __classPrivateFieldGet(this, _SyncAvroFileWriter_metadata, "f").set("avro.codec", encodeString(__classPrivateFieldGet(this, _SyncAvroFileWriter_codec, "f")));
+        }
+    }
+    /**
+     * Appends a record to the pending block, flushing when the block size is met.
+     */
+    append(record) {
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_ensureOpen).call(this);
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_ensureHeaderWritten).call(this);
+        if (!__classPrivateFieldGet(this, _SyncAvroFileWriter_schemaType, "f").isValid(record)) {
+            throw new Error("Record does not conform to the schema.");
+        }
+        const recordBytes = __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_encodeRecord).call(this, record);
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_pendingRecords, "f").push(recordBytes);
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_pendingBytes, __classPrivateFieldGet(this, _SyncAvroFileWriter_pendingBytes, "f") + recordBytes.length, "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_pendingCount, __classPrivateFieldGet(this, _SyncAvroFileWriter_pendingCount, "f") + 1, "f");
+        if (__classPrivateFieldGet(this, _SyncAvroFileWriter_pendingBytes, "f") >= __classPrivateFieldGet(this, _SyncAvroFileWriter_blockSize, "f")) {
+            this.flushBlock();
+        }
+    }
+    /**
+     * Flushes any pending data and prevents further writes.
+     */
+    close() {
+        if (__classPrivateFieldGet(this, _SyncAvroFileWriter_closed, "f")) {
+            return;
+        }
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_ensureHeaderWritten).call(this);
+        this.flushBlock();
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_closed, true, "f");
+    }
+    /**
+     * Forces pending data into a block immediately.
+     */
+    flushBlock() {
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_ensureOpen).call(this);
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_ensureHeaderWritten).call(this);
+        if (__classPrivateFieldGet(this, _SyncAvroFileWriter_pendingCount, "f") === 0) {
+            return;
+        }
+        const combined = __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_combinePending).call(this);
+        const encoded = __classPrivateFieldGet(this, _SyncAvroFileWriter_encoder, "f").encode(combined);
+        const block = {
+            count: BigInt(__classPrivateFieldGet(this, _SyncAvroFileWriter_pendingCount, "f")),
+            data: encoded,
+            sync: __classPrivateFieldGet(this, _SyncAvroFileWriter_syncMarker, "f"),
+        };
+        BLOCK_TYPE.writeSync(__classPrivateFieldGet(this, _SyncAvroFileWriter_tap, "f"), block);
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_pendingRecords, [], "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_pendingBytes, 0, "f");
+        __classPrivateFieldSet(this, _SyncAvroFileWriter_pendingCount, 0, "f");
+    }
+}
+_SyncAvroFileWriter_tap = new WeakMap(), _SyncAvroFileWriter_schemaType = new WeakMap(), _SyncAvroFileWriter_codec = new WeakMap(), _SyncAvroFileWriter_encoder = new WeakMap(), _SyncAvroFileWriter_blockSize = new WeakMap(), _SyncAvroFileWriter_syncMarker = new WeakMap(), _SyncAvroFileWriter_metadata = new WeakMap(), _SyncAvroFileWriter_pendingRecords = new WeakMap(), _SyncAvroFileWriter_pendingBytes = new WeakMap(), _SyncAvroFileWriter_pendingCount = new WeakMap(), _SyncAvroFileWriter_headerWritten = new WeakMap(), _SyncAvroFileWriter_closed = new WeakMap(), _SyncAvroFileWriter_builtInEncoders = new WeakMap(), _SyncAvroFileWriter_customEncoders = new WeakMap(), _SyncAvroFileWriter_instances = new WeakSet(), _SyncAvroFileWriter_ensureOpen = function _SyncAvroFileWriter_ensureOpen() {
+    if (__classPrivateFieldGet(this, _SyncAvroFileWriter_closed, "f")) {
+        throw new Error("Avro writer is already closed.");
+    }
+}, _SyncAvroFileWriter_ensureHeaderWritten = function _SyncAvroFileWriter_ensureHeaderWritten() {
+    if (__classPrivateFieldGet(this, _SyncAvroFileWriter_headerWritten, "f")) {
+        return;
+    }
+    __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_writeHeader).call(this);
+}, _SyncAvroFileWriter_writeHeader = function _SyncAvroFileWriter_writeHeader() {
+    const header = {
+        magic: MAGIC_BYTES,
+        meta: __classPrivateFieldGet(this, _SyncAvroFileWriter_metadata, "f"),
+        sync: __classPrivateFieldGet(this, _SyncAvroFileWriter_syncMarker, "f"),
+    };
+    HEADER_TYPE.writeSync(__classPrivateFieldGet(this, _SyncAvroFileWriter_tap, "f"), header);
+    __classPrivateFieldSet(this, _SyncAvroFileWriter_headerWritten, true, "f");
+}, _SyncAvroFileWriter_validateBlockSize = function _SyncAvroFileWriter_validateBlockSize(blockSize) {
+    const size = blockSize ?? DEFAULT_BLOCK_SIZE_BYTES;
+    if (!Number.isFinite(size) || !Number.isInteger(size) || size <= 0) {
+        throw new RangeError("blockSize must be a positive integer byte count.");
+    }
+    return size;
+}, _SyncAvroFileWriter_initializeSyncMarker = function _SyncAvroFileWriter_initializeSyncMarker(marker) {
+    if (!marker) {
+        const generated = new Uint8Array(SYNC_MARKER_SIZE);
+        crypto.getRandomValues(generated);
+        return generated;
+    }
+    if (marker.length !== SYNC_MARKER_SIZE) {
+        throw new Error(`Sync marker must be ${SYNC_MARKER_SIZE} bytes long.`);
+    }
+    return marker.slice();
+}, _SyncAvroFileWriter_validateCustomEncoders = function _SyncAvroFileWriter_validateCustomEncoders(encoders) {
+    if (!encoders) {
+        return {};
+    }
+    for (const codec of Object.keys(encoders)) {
+        if (codec in __classPrivateFieldGet(this, _SyncAvroFileWriter_builtInEncoders, "f")) {
+            throw new Error(`Cannot override built-in encoder for codec: ${codec}`);
+        }
+    }
+    return { ...encoders };
+}, _SyncAvroFileWriter_resolveEncoder = function _SyncAvroFileWriter_resolveEncoder(codec) {
+    if (codec in __classPrivateFieldGet(this, _SyncAvroFileWriter_builtInEncoders, "f")) {
+        return __classPrivateFieldGet(this, _SyncAvroFileWriter_builtInEncoders, "f")[codec];
+    }
+    if (codec in __classPrivateFieldGet(this, _SyncAvroFileWriter_customEncoders, "f")) {
+        return __classPrivateFieldGet(this, _SyncAvroFileWriter_customEncoders, "f")[codec];
+    }
+    throw new Error(`Unsupported codec: ${codec}. Provide a custom encoder.`);
+}, _SyncAvroFileWriter_buildMetadata = function _SyncAvroFileWriter_buildMetadata(input) {
+    const metadata = new Map();
+    if (!input) {
+        return metadata;
+    }
+    const setEntry = (key, value) => {
+        __classPrivateFieldGet(this, _SyncAvroFileWriter_instances, "m", _SyncAvroFileWriter_assertMetadataKey).call(this, key);
+        if (value instanceof Uint8Array) {
+            metadata.set(key, value.slice());
+        }
+        else {
+            metadata.set(key, encodeString(value));
+        }
+    };
+    if (input instanceof Map) {
+        for (const [key, value] of input.entries()) {
+            setEntry(key, value);
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(input)) {
+            setEntry(key, value);
+        }
+    }
+    return metadata;
+}, _SyncAvroFileWriter_assertMetadataKey = function _SyncAvroFileWriter_assertMetadataKey(key) {
+    if (typeof key !== "string" || key.length === 0) {
+        throw new Error("Metadata keys must be non-empty strings.");
+    }
+    if (RESERVED_METADATA_KEYS.has(key)) {
+        throw new Error(`Metadata key "${key}" is reserved and managed by the Avro writer.`);
+    }
+}, _SyncAvroFileWriter_encodeRecord = function _SyncAvroFileWriter_encodeRecord(record) {
+    const buffer = __classPrivateFieldGet(this, _SyncAvroFileWriter_schemaType, "f").toSyncBuffer(record);
+    return new Uint8Array(buffer);
+}, _SyncAvroFileWriter_combinePending = function _SyncAvroFileWriter_combinePending() {
+    const combined = new Uint8Array(__classPrivateFieldGet(this, _SyncAvroFileWriter_pendingBytes, "f"));
+    let offset = 0;
+    for (const record of __classPrivateFieldGet(this, _SyncAvroFileWriter_pendingRecords, "f")) {
+        combined.set(record, offset);
+        offset += record.length;
+    }
+    return combined;
+};

package/esm/serialization/buffers/blob_readable_buffer.d.ts

@@ -9,7 +9,7 @@ import type { IReadableBuffer } from "./buffer.js";
  * Key features:
  * - Blob-backed: Reads data directly from the Blob asynchronously.
  * - Random access: Supports reading at arbitrary byte offsets.
- * - Bounds checking: Operations that would exceed buffer bounds are safely ignored or return undefined.
+ * - Bounds checking: Operations that exceed buffer bounds throw ReadBufferError.
  * - Memory efficient: Doesn't load data into memory.
  *
  * @example
@@ -41,9 +41,10 @@ export declare class BlobReadableBuffer implements IReadableBuffer {
      *
      * @param offset The byte offset to start reading from (0-based).
      * @param size The number of bytes to read.
-     * @returns A Promise that resolves to a new Uint8Array containing the read bytes, or undefined if the read would exceed buffer bounds.
+     * @returns A Promise that resolves to a new Uint8Array containing the read bytes.
+     * @throws ReadBufferError if the requested range is out of bounds.
      */
-    read(offset: number, size: number): Promise<Uint8Array | undefined>;
+    read(offset: number, size: number): Promise<Uint8Array>;
     /**
      * Checks if more data can be read starting at the given offset.
      * @param offset The byte offset to check.

package/esm/serialization/buffers/blob_readable_buffer.js

@@ -10,6 +10,7 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
     return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
 };
 var _BlobReadableBuffer_blob;
+import { ReadBufferError } from "./buffer_error.js";
 /**
  * A read-only buffer implementation that provides random access read operations
  * on data from a Blob. This class is useful for working with binary data
@@ -20,7 +21,7 @@ var _BlobReadableBuffer_blob;
  * Key features:
  * - Blob-backed: Reads data directly from the Blob asynchronously.
  * - Random access: Supports reading at arbitrary byte offsets.
- * - Bounds checking: Operations that would exceed buffer bounds are safely ignored or return undefined.
+ * - Bounds checking: Operations that exceed buffer bounds throw ReadBufferError.
  * - Memory efficient: Doesn't load data into memory.
  *
  * @example
@@ -57,11 +58,16 @@ export class BlobReadableBuffer {
      *
      * @param offset The byte offset to start reading from (0-based).
      * @param size The number of bytes to read.
-     * @returns A Promise that resolves to a new Uint8Array containing the read bytes, or undefined if the read would exceed buffer bounds.
+     * @returns A Promise that resolves to a new Uint8Array containing the read bytes.
+     * @throws ReadBufferError if the requested range is out of bounds.
      */
     async read(offset, size) {
-        if (offset + size > __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size)
-            return undefined;
+        if (offset < 0 || size < 0) {
+            throw new ReadBufferError(`Offset and size must be non-negative. Got offset=${offset}, size=${size}`, offset, size, __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size);
+        }
+        if (offset + size > __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size) {
+            throw new ReadBufferError(`Operation exceeds buffer bounds. offset=${offset}, size=${size}, bufferLength=${__classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size}`, offset, size, __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size);
+        }
         // Read directly from the Blob
         const sliced = __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").slice(offset, offset + size);
         const arrayBuffer = await sliced.arrayBuffer();
@@ -73,8 +79,16 @@ export class BlobReadableBuffer {
      * @returns True if at least one byte can be read from the offset.
      */
     async canReadMore(offset) {
-        const result = await this.read(offset, 1);
-        return result !== undefined;
+        try {
+            await this.read(offset, 1);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof ReadBufferError) {
+                return false;
+            }
+            throw err;
+        }
     }
 }
 _BlobReadableBuffer_blob = new WeakMap();

package/esm/serialization/buffers/buffer.d.ts

@@ -4,8 +4,11 @@
 export interface IReadableBuffer {
     /**
      * Reads a portion of the buffer starting at offset with the given size.
+     *
+     * @throws ReadBufferError when the requested range is invalid or exceeds the
+     * available bounds.
      */
-    read(offset: number, size: number): Promise<Uint8Array | undefined>;
+    read(offset: number, size: number): Promise<Uint8Array>;
     /**
      * Checks if more data can be read starting at the given offset.
      */
@@ -18,6 +21,8 @@ export interface IWritableBuffer {
     /**
      * Appends bytes to the buffer, advancing its internal write cursor when the
      * operation succeeds.
+     *
+     * @throws WriteBufferError when the buffer cannot accept the requested bytes.
      */
     appendBytes(data: Uint8Array): Promise<void>;
     /**