@sachitv/avro-typescript 0.4.0

package/esm/serialization/avro_file_parser.js

@@ -0,0 +1,191 @@
+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 _AvroFileParser_instances, _AvroFileParser_buffer, _AvroFileParser_header, _AvroFileParser_headerTap, _AvroFileParser_readerSchema, _AvroFileParser_readerType, _AvroFileParser_resolver, _AvroFileParser_decoders, _AvroFileParser_builtInDecoders, _AvroFileParser_getDecoder, _AvroFileParser_parseHeader, _AvroFileParser_getResolver, _AvroFileParser_createReaderType;
+import { createType } from "../type/create_type.js";
+import { Type } from "../schemas/type.js";
+import { ReadableTap } from "./tap.js";
+import { DeflateDecoder } from "./decoders/deflate_decoder.js";
+import { NullDecoder } from "./decoders/null_decoder.js";
+import { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES } from "./avro_constants.js";
+// Re-export constants for backward compatibility
+export { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES };
+/**
+ * Parser for Avro object container files that reads headers, resolves schemas,
+ * and streams decoded records from readable buffers.
+ */
+export class AvroFileParser {
+    /**
+     * Creates a new AvroFileParser.
+     *
+     * @param buffer The readable buffer containing Avro data.
+     * @param options Configuration options for parsing.
+     */
+    constructor(buffer, options) {
+        _AvroFileParser_instances.add(this);
+        _AvroFileParser_buffer.set(this, void 0);
+        _AvroFileParser_header.set(this, void 0);
+        _AvroFileParser_headerTap.set(this, void 0);
+        _AvroFileParser_readerSchema.set(this, void 0);
+        _AvroFileParser_readerType.set(this, void 0);
+        _AvroFileParser_resolver.set(this, void 0);
+        _AvroFileParser_decoders.set(this, void 0);
+        _AvroFileParser_builtInDecoders.set(this, void 0);
+        __classPrivateFieldSet(this, _AvroFileParser_buffer, buffer, "f");
+        __classPrivateFieldSet(this, _AvroFileParser_readerSchema, options?.readerSchema, "f");
+        // Initialize built-in decoders
+        __classPrivateFieldSet(this, _AvroFileParser_builtInDecoders, {
+            "null": new NullDecoder(),
+            "deflate": new DeflateDecoder(),
+        }, "f");
+        // Validate custom decoders (cannot override built-ins)
+        const customDecoders = options?.decoders || {};
+        for (const codec of Object.keys(customDecoders)) {
+            if (codec in __classPrivateFieldGet(this, _AvroFileParser_builtInDecoders, "f")) {
+                throw new Error(`Cannot override built-in decoder for codec: ${codec}`);
+            }
+        }
+        __classPrivateFieldSet(this, _AvroFileParser_decoders, { ...customDecoders }, "f");
+    }
+    /**
+     * Gets the parsed Avro file header with proper typing.
+     *
+     * @returns Promise that resolves to the parsed header information.
+     * @throws Error if the file is not a valid Avro file.
+     */
+    async getHeader() {
+        const header = await __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_parseHeader).call(this);
+        return {
+            magic: header.magic,
+            meta: header.meta,
+            sync: header.sync,
+        };
+    }
+    /**
+     * Asynchronously iterates over all records in the Avro file.
+     *
+     * @returns AsyncIterableIterator that yields each record.
+     * @throws Error if the file contains invalid data or is corrupted.
+     */
+    async *iterRecords() {
+        const header = await __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_parseHeader).call(this);
+        const { schemaType, meta } = header;
+        const resolver = __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_getResolver).call(this, schemaType);
+        // Get the codec from metadata
+        const codecBytes = meta.get("avro.codec");
+        const codecStr = (() => {
+            if (codecBytes === undefined) {
+                return "null";
+            }
+            const decoded = new TextDecoder().decode(codecBytes);
+            return decoded.length === 0 ? "null" : decoded;
+        })();
+        const decoder = __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_getDecoder).call(this, codecStr);
+        // Use the tap that's positioned after the header
+        const tap = __classPrivateFieldGet(this, _AvroFileParser_headerTap, "f");
+        while (await tap.canReadMore()) {
+            const block = await BLOCK_TYPE.read(tap);
+            // Decompress block data if needed
+            const decompressedData = await decoder.decode(block.data);
+            const arrayBuffer = new ArrayBuffer(decompressedData.length);
+            new Uint8Array(arrayBuffer).set(decompressedData);
+            const recordTap = new ReadableTap(arrayBuffer);
+            // Yield each record in the block
+            for (let i = 0n; i < block.count; i += 1n) {
+                const record = resolver
+                    ? await resolver.read(recordTap)
+                    : await schemaType.read(recordTap);
+                yield record;
+            }
+        }
+    }
+}
+_AvroFileParser_buffer = new WeakMap(), _AvroFileParser_header = new WeakMap(), _AvroFileParser_headerTap = new WeakMap(), _AvroFileParser_readerSchema = new WeakMap(), _AvroFileParser_readerType = new WeakMap(), _AvroFileParser_resolver = new WeakMap(), _AvroFileParser_decoders = new WeakMap(), _AvroFileParser_builtInDecoders = new WeakMap(), _AvroFileParser_instances = new WeakSet(), _AvroFileParser_getDecoder = function _AvroFileParser_getDecoder(codec) {
+    // Check built-in decoders first
+    if (codec in __classPrivateFieldGet(this, _AvroFileParser_builtInDecoders, "f")) {
+        return __classPrivateFieldGet(this, _AvroFileParser_builtInDecoders, "f")[codec];
+    }
+    // Check custom decoders
+    if (codec in __classPrivateFieldGet(this, _AvroFileParser_decoders, "f")) {
+        return __classPrivateFieldGet(this, _AvroFileParser_decoders, "f")[codec];
+    }
+    throw new Error(`Unsupported codec: ${codec}. Provide a custom decoder.`);
+}, _AvroFileParser_parseHeader = 
+/**
+ * Private method to parse the Avro file header and cache it.
+ *
+ * @returns Promise that resolves to the parsed header information.
+ * @throws Error if the file is not a valid Avro file.
+ */
+async function _AvroFileParser_parseHeader() {
+    if (__classPrivateFieldGet(this, _AvroFileParser_header, "f")) {
+        return __classPrivateFieldGet(this, _AvroFileParser_header, "f");
+    }
+    const tap = new ReadableTap(__classPrivateFieldGet(this, _AvroFileParser_buffer, "f"));
+    const header = await HEADER_TYPE.read(tap);
+    // Validate magic bytes
+    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");
+        }
+    }
+    // Extract metadata
+    const meta = header.meta;
+    // Read and parse the schema
+    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));
+    // Validate that we have a decoder for the codec
+    const codec = meta.get("avro.codec");
+    if (codec && codec.length > 0) {
+        const codecStr = new TextDecoder().decode(codec);
+        // This will throw if codec is not supported
+        __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_getDecoder).call(this, codecStr);
+    }
+    const sync = header.sync;
+    __classPrivateFieldSet(this, _AvroFileParser_header, {
+        magic,
+        meta,
+        sync,
+        schemaType,
+    }, "f");
+    // Store the tap at its current position for reading blocks
+    __classPrivateFieldSet(this, _AvroFileParser_headerTap, tap, "f");
+    return __classPrivateFieldGet(this, _AvroFileParser_header, "f");
+}, _AvroFileParser_getResolver = function _AvroFileParser_getResolver(writerType) {
+    if (__classPrivateFieldGet(this, _AvroFileParser_readerSchema, "f") === undefined || __classPrivateFieldGet(this, _AvroFileParser_readerSchema, "f") === null) {
+        return undefined;
+    }
+    if (!__classPrivateFieldGet(this, _AvroFileParser_readerType, "f")) {
+        __classPrivateFieldSet(this, _AvroFileParser_readerType, __classPrivateFieldGet(this, _AvroFileParser_instances, "m", _AvroFileParser_createReaderType).call(this, __classPrivateFieldGet(this, _AvroFileParser_readerSchema, "f")), "f");
+    }
+    if (!__classPrivateFieldGet(this, _AvroFileParser_resolver, "f")) {
+        __classPrivateFieldSet(this, _AvroFileParser_resolver, __classPrivateFieldGet(this, _AvroFileParser_readerType, "f").createResolver(writerType), "f");
+    }
+    return __classPrivateFieldGet(this, _AvroFileParser_resolver, "f");
+}, _AvroFileParser_createReaderType = function _AvroFileParser_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);
+};

package/esm/serialization/avro_file_writer.d.ts

@@ -0,0 +1,63 @@
+import { type SchemaLike } from "../type/create_type.js";
+import type { IWritableBuffer } from "./buffers/buffer.js";
+import type { EncoderRegistry } from "./encoders/encoder.js";
+/**
+ * Type for initializing metadata in an Avro file header.
+ * Can be a Map of string keys to Uint8Array values, or a plain object with string or Uint8Array values.
+ */
+export type MetadataInit = Map<string, Uint8Array> | Record<string, string | Uint8Array>;
+/**
+ * Options for configuring an AvroFileWriter.
+ */
+export interface AvroWriterOptions {
+    /**
+     * The Avro schema defining the structure of records to be written.
+     */
+    schema: SchemaLike;
+    /**
+     * The compression codec to use for data blocks. Defaults to "null" (no compression).
+     */
+    codec?: string;
+    /**
+     * The maximum size in bytes for data blocks. Defaults to 64000 bytes.
+     */
+    blockSize?: number;
+    /**
+     * A 16-byte sync marker used to delineate blocks. If not provided, a random one is generated.
+     */
+    syncMarker?: Uint8Array;
+    /**
+     * Additional metadata to include in the Avro file header.
+     */
+    metadata?: MetadataInit;
+    /**
+     * Custom encoders for compression codecs not built into the library.
+     */
+    encoders?: EncoderRegistry;
+}
+/**
+ * Low-level writer for Avro object container files that manages schema
+ * serialization, block encoding, metadata, and sync markers.
+ */
+export declare class AvroFileWriter {
+    #private;
+    /**
+     * Creates a new AvroFileWriter.
+     * @param buffer The writable buffer to write to.
+     * @param options Configuration options including schema and codec.
+     */
+    constructor(buffer: IWritableBuffer, options: AvroWriterOptions);
+    /**
+     * Append a single record to the file.
+     */
+    append(record: unknown): Promise<void>;
+    /**
+     * Flush pending data and prevent further writes.
+     */
+    close(): Promise<void>;
+    /**
+     * Manually flush pending records to a block.
+     * This can be called to force writing of accumulated records before the block size threshold is reached.
+     */
+    flushBlock(): Promise<void>;
+}

package/esm/serialization/avro_file_writer.js

@@ -0,0 +1,235 @@
+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 _AvroFileWriter_instances, _AvroFileWriter_tap, _AvroFileWriter_schemaType, _AvroFileWriter_codec, _AvroFileWriter_encoder, _AvroFileWriter_blockSize, _AvroFileWriter_syncMarker, _AvroFileWriter_metadata, _AvroFileWriter_pendingRecords, _AvroFileWriter_pendingBytes, _AvroFileWriter_pendingCount, _AvroFileWriter_headerPromise, _AvroFileWriter_headerWritten, _AvroFileWriter_closed, _AvroFileWriter_builtInEncoders, _AvroFileWriter_customEncoders, _AvroFileWriter_ensureOpen, _AvroFileWriter_validateBlockSize, _AvroFileWriter_initializeSyncMarker, _AvroFileWriter_validateCustomEncoders, _AvroFileWriter_resolveEncoder, _AvroFileWriter_buildMetadata, _AvroFileWriter_assertMetadataKey, _AvroFileWriter_ensureHeaderWritten, _AvroFileWriter_writeHeader, _AvroFileWriter_encodeRecord, _AvroFileWriter_combinePending;
+import { createType } from "../type/create_type.js";
+import { WritableTap } from "./tap.js";
+import { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES } from "./avro_constants.js";
+import { DeflateEncoder } from "./encoders/deflate_encoder.js";
+import { NullEncoder } from "./encoders/null_encoder.js";
+import { encode as encodeString } from "./text_encoding.js";
+/**
+ * Default block size in bytes for Avro data blocks.
+ * Set to 64000 to match the default used by the Java Avro libraries.
+ */
+const DEFAULT_BLOCK_SIZE_BYTES = 64000;
+const SYNC_MARKER_SIZE = 16;
+const RESERVED_METADATA_KEYS = new Set(["avro.schema", "avro.codec"]);
+/**
+ * Low-level writer for Avro object container files that manages schema
+ * serialization, block encoding, metadata, and sync markers.
+ */
+export class AvroFileWriter {
+    /**
+     * Creates a new AvroFileWriter.
+     * @param buffer The writable buffer to write to.
+     * @param options Configuration options including schema and codec.
+     */
+    constructor(buffer, options) {
+        _AvroFileWriter_instances.add(this);
+        _AvroFileWriter_tap.set(this, void 0);
+        _AvroFileWriter_schemaType.set(this, void 0);
+        _AvroFileWriter_codec.set(this, void 0);
+        _AvroFileWriter_encoder.set(this, void 0);
+        _AvroFileWriter_blockSize.set(this, void 0);
+        _AvroFileWriter_syncMarker.set(this, void 0);
+        _AvroFileWriter_metadata.set(this, void 0);
+        _AvroFileWriter_pendingRecords.set(this, []);
+        _AvroFileWriter_pendingBytes.set(this, 0);
+        _AvroFileWriter_pendingCount.set(this, 0);
+        _AvroFileWriter_headerPromise.set(this, void 0);
+        _AvroFileWriter_headerWritten.set(this, false);
+        _AvroFileWriter_closed.set(this, false);
+        _AvroFileWriter_builtInEncoders.set(this, void 0);
+        _AvroFileWriter_customEncoders.set(this, void 0);
+        if (!options || !options.schema) {
+            throw new Error("Avro writer requires a schema.");
+        }
+        __classPrivateFieldSet(this, _AvroFileWriter_tap, new WritableTap(buffer), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_schemaType, createType(options.schema), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_codec, options.codec ?? "null", "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_blockSize, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_validateBlockSize).call(this, options.blockSize), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_syncMarker, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_initializeSyncMarker).call(this, options.syncMarker), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_builtInEncoders, {
+            "null": new NullEncoder(),
+            "deflate": new DeflateEncoder(),
+        }, "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_customEncoders, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_validateCustomEncoders).call(this, options.encoders), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_encoder, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_resolveEncoder).call(this, __classPrivateFieldGet(this, _AvroFileWriter_codec, "f")), "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_metadata, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_buildMetadata).call(this, options.metadata), "f");
+        __classPrivateFieldGet(this, _AvroFileWriter_metadata, "f").set("avro.schema", encodeString(JSON.stringify(__classPrivateFieldGet(this, _AvroFileWriter_schemaType, "f").toJSON())));
+        if (__classPrivateFieldGet(this, _AvroFileWriter_codec, "f") !== "null") {
+            __classPrivateFieldGet(this, _AvroFileWriter_metadata, "f").set("avro.codec", encodeString(__classPrivateFieldGet(this, _AvroFileWriter_codec, "f")));
+        }
+    }
+    /**
+     * Append a single record to the file.
+     */
+    async append(record) {
+        __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_ensureOpen).call(this);
+        await __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_ensureHeaderWritten).call(this);
+        if (!__classPrivateFieldGet(this, _AvroFileWriter_schemaType, "f").isValid(record)) {
+            throw new Error("Record does not conform to the schema.");
+        }
+        const recordBytes = await __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_encodeRecord).call(this, record);
+        __classPrivateFieldGet(this, _AvroFileWriter_pendingRecords, "f").push(recordBytes);
+        __classPrivateFieldSet(this, _AvroFileWriter_pendingBytes, __classPrivateFieldGet(this, _AvroFileWriter_pendingBytes, "f") + recordBytes.length, "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_pendingCount, __classPrivateFieldGet(this, _AvroFileWriter_pendingCount, "f") + 1, "f");
+        if (__classPrivateFieldGet(this, _AvroFileWriter_pendingBytes, "f") >= __classPrivateFieldGet(this, _AvroFileWriter_blockSize, "f")) {
+            await this.flushBlock();
+        }
+    }
+    /**
+     * Flush pending data and prevent further writes.
+     */
+    async close() {
+        if (__classPrivateFieldGet(this, _AvroFileWriter_closed, "f")) {
+            return;
+        }
+        await __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_ensureHeaderWritten).call(this);
+        await this.flushBlock();
+        __classPrivateFieldSet(this, _AvroFileWriter_closed, true, "f");
+    }
+    /**
+     * Manually flush pending records to a block.
+     * This can be called to force writing of accumulated records before the block size threshold is reached.
+     */
+    async flushBlock() {
+        __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_ensureOpen).call(this);
+        await __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_ensureHeaderWritten).call(this);
+        if (__classPrivateFieldGet(this, _AvroFileWriter_pendingCount, "f") === 0) {
+            return;
+        }
+        const combined = __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_combinePending).call(this);
+        const encoded = await __classPrivateFieldGet(this, _AvroFileWriter_encoder, "f").encode(combined);
+        const block = {
+            count: BigInt(__classPrivateFieldGet(this, _AvroFileWriter_pendingCount, "f")),
+            data: encoded,
+            sync: __classPrivateFieldGet(this, _AvroFileWriter_syncMarker, "f"),
+        };
+        await BLOCK_TYPE.write(__classPrivateFieldGet(this, _AvroFileWriter_tap, "f"), block);
+        __classPrivateFieldSet(this, _AvroFileWriter_pendingRecords, [], "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_pendingBytes, 0, "f");
+        __classPrivateFieldSet(this, _AvroFileWriter_pendingCount, 0, "f");
+    }
+}
+_AvroFileWriter_tap = new WeakMap(), _AvroFileWriter_schemaType = new WeakMap(), _AvroFileWriter_codec = new WeakMap(), _AvroFileWriter_encoder = new WeakMap(), _AvroFileWriter_blockSize = new WeakMap(), _AvroFileWriter_syncMarker = new WeakMap(), _AvroFileWriter_metadata = new WeakMap(), _AvroFileWriter_pendingRecords = new WeakMap(), _AvroFileWriter_pendingBytes = new WeakMap(), _AvroFileWriter_pendingCount = new WeakMap(), _AvroFileWriter_headerPromise = new WeakMap(), _AvroFileWriter_headerWritten = new WeakMap(), _AvroFileWriter_closed = new WeakMap(), _AvroFileWriter_builtInEncoders = new WeakMap(), _AvroFileWriter_customEncoders = new WeakMap(), _AvroFileWriter_instances = new WeakSet(), _AvroFileWriter_ensureOpen = function _AvroFileWriter_ensureOpen() {
+    if (__classPrivateFieldGet(this, _AvroFileWriter_closed, "f")) {
+        throw new Error("Avro writer is already closed.");
+    }
+}, _AvroFileWriter_validateBlockSize = function _AvroFileWriter_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;
+}, _AvroFileWriter_initializeSyncMarker = function _AvroFileWriter_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();
+}, _AvroFileWriter_validateCustomEncoders = function _AvroFileWriter_validateCustomEncoders(encoders) {
+    if (!encoders) {
+        return {};
+    }
+    for (const codec of Object.keys(encoders)) {
+        if (codec in __classPrivateFieldGet(this, _AvroFileWriter_builtInEncoders, "f")) {
+            throw new Error(`Cannot override built-in encoder for codec: ${codec}`);
+        }
+    }
+    return { ...encoders };
+}, _AvroFileWriter_resolveEncoder = function _AvroFileWriter_resolveEncoder(codec) {
+    if (codec in __classPrivateFieldGet(this, _AvroFileWriter_builtInEncoders, "f")) {
+        return __classPrivateFieldGet(this, _AvroFileWriter_builtInEncoders, "f")[codec];
+    }
+    if (codec in __classPrivateFieldGet(this, _AvroFileWriter_customEncoders, "f")) {
+        return __classPrivateFieldGet(this, _AvroFileWriter_customEncoders, "f")[codec];
+    }
+    throw new Error(`Unsupported codec: ${codec}. Provide a custom encoder.`);
+}, _AvroFileWriter_buildMetadata = function _AvroFileWriter_buildMetadata(input) {
+    const metadata = new Map();
+    if (!input) {
+        return metadata;
+    }
+    const setEntry = (key, value) => {
+        __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_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;
+}, _AvroFileWriter_assertMetadataKey = function _AvroFileWriter_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.`);
+    }
+}, _AvroFileWriter_ensureHeaderWritten = 
+/**
+ * Ensures the header has been written to the output.
+ */
+async function _AvroFileWriter_ensureHeaderWritten() {
+    if (__classPrivateFieldGet(this, _AvroFileWriter_headerWritten, "f")) {
+        return;
+    }
+    if (!__classPrivateFieldGet(this, _AvroFileWriter_headerPromise, "f")) {
+        __classPrivateFieldSet(this, _AvroFileWriter_headerPromise, __classPrivateFieldGet(this, _AvroFileWriter_instances, "m", _AvroFileWriter_writeHeader).call(this), "f");
+    }
+    await __classPrivateFieldGet(this, _AvroFileWriter_headerPromise, "f");
+}, _AvroFileWriter_writeHeader = 
+/**
+ * Writes the Avro file header to the output.
+ */
+async function _AvroFileWriter_writeHeader() {
+    const header = {
+        magic: MAGIC_BYTES,
+        meta: __classPrivateFieldGet(this, _AvroFileWriter_metadata, "f"),
+        sync: __classPrivateFieldGet(this, _AvroFileWriter_syncMarker, "f"),
+    };
+    await HEADER_TYPE.write(__classPrivateFieldGet(this, _AvroFileWriter_tap, "f"), header);
+    __classPrivateFieldSet(this, _AvroFileWriter_headerWritten, true, "f");
+}, _AvroFileWriter_encodeRecord = 
+/**
+ * Encodes a record to bytes using the schema.
+ * @param record The record to encode.
+ * @returns The encoded record bytes.
+ */
+async function _AvroFileWriter_encodeRecord(record) {
+    const buffer = await __classPrivateFieldGet(this, _AvroFileWriter_schemaType, "f").toBuffer(record);
+    return new Uint8Array(buffer);
+}, _AvroFileWriter_combinePending = function _AvroFileWriter_combinePending() {
+    const combined = new Uint8Array(__classPrivateFieldGet(this, _AvroFileWriter_pendingBytes, "f"));
+    let offset = 0;
+    for (const record of __classPrivateFieldGet(this, _AvroFileWriter_pendingRecords, "f")) {
+        combined.set(record, offset);
+        offset += record.length;
+    }
+    return combined;
+};

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

@@ -0,0 +1,53 @@
+import type { IReadableBuffer } from "./buffer.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
+ * from files, network responses, or other Blob sources.
+ *
+ * Reads are performed asynchronously directly from the 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.
+ * - Memory efficient: Doesn't load data into memory.
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob([new Uint8Array([1, 2, 3, 4])]);
+ * const buffer = new BlobReadableBuffer(blob);
+ *
+ * // Read some data asynchronously
+ * const data = await buffer.read(0, 4); // Returns Uint8Array([1, 2, 3, 4])
+ * ```
+ */
+export declare class BlobReadableBuffer implements IReadableBuffer {
+    #private;
+    /**
+     * Creates a new BlobReadableBuffer from the provided Blob.
+     *
+     * @param blob The Blob to read data from.
+     */
+    constructor(blob: Blob);
+    /**
+     * Gets the total length of the buffer in bytes.
+     *
+     * @returns The buffer length in bytes.
+     */
+    length(): Promise<number>;
+    /**
+     * Reads a sequence of bytes from the buffer starting at the specified offset.
+     * Reads asynchronously from the Blob.
+     *
+     * @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.
+     */
+    read(offset: number, size: number): Promise<Uint8Array | undefined>;
+    /**
+     * Checks if more data can be read starting at the given offset.
+     * @param offset The byte offset to check.
+     * @returns True if at least one byte can be read from the offset.
+     */
+    canReadMore(offset: number): Promise<boolean>;
+}

package/esm/serialization/buffers/blob_readable_buffer.js

@@ -0,0 +1,80 @@
+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 _BlobReadableBuffer_blob;
+/**
+ * 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
+ * from files, network responses, or other Blob sources.
+ *
+ * Reads are performed asynchronously directly from the 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.
+ * - Memory efficient: Doesn't load data into memory.
+ *
+ * @example
+ * ```typescript
+ * const blob = new Blob([new Uint8Array([1, 2, 3, 4])]);
+ * const buffer = new BlobReadableBuffer(blob);
+ *
+ * // Read some data asynchronously
+ * const data = await buffer.read(0, 4); // Returns Uint8Array([1, 2, 3, 4])
+ * ```
+ */
+export class BlobReadableBuffer {
+    /**
+     * Creates a new BlobReadableBuffer from the provided Blob.
+     *
+     * @param blob The Blob to read data from.
+     */
+    constructor(blob) {
+        _BlobReadableBuffer_blob.set(this, void 0);
+        __classPrivateFieldSet(this, _BlobReadableBuffer_blob, blob, "f");
+    }
+    /**
+     * Gets the total length of the buffer in bytes.
+     *
+     * @returns The buffer length in bytes.
+     */
+    // deno-lint-ignore require-await
+    async length() {
+        return __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size;
+    }
+    /**
+     * Reads a sequence of bytes from the buffer starting at the specified offset.
+     * Reads asynchronously from the Blob.
+     *
+     * @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.
+     */
+    async read(offset, size) {
+        if (offset + size > __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").size)
+            return undefined;
+        // Read directly from the Blob
+        const sliced = __classPrivateFieldGet(this, _BlobReadableBuffer_blob, "f").slice(offset, offset + size);
+        const arrayBuffer = await sliced.arrayBuffer();
+        return new Uint8Array(arrayBuffer);
+    }
+    /**
+     * Checks if more data can be read starting at the given offset.
+     * @param offset The byte offset to check.
+     * @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;
+    }
+}
+_BlobReadableBuffer_blob = new WeakMap();

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

@@ -0,0 +1,37 @@
+/**
+ * Interface describing a random-access readable buffer.
+ */
+export interface IReadableBuffer {
+    /**
+     * Reads a portion of the buffer starting at offset with the given size.
+     */
+    read(offset: number, size: number): Promise<Uint8Array | undefined>;
+    /**
+     * Checks if more data can be read starting at the given offset.
+     */
+    canReadMore(offset: number): Promise<boolean>;
+}
+/**
+ * Interface describing an append-only writable buffer.
+ */
+export interface IWritableBuffer {
+    /**
+     * Appends bytes to the buffer, advancing its internal write cursor when the
+     * operation succeeds.
+     */
+    appendBytes(data: Uint8Array): Promise<void>;
+    /**
+     * Returns whether the buffer can continue accepting writes. Implementations
+     * should flip this to `false` after a write would exceed capacity so callers
+     * can detect the overflow condition.
+     */
+    isValid(): Promise<boolean>;
+    /**
+     * Checks if the buffer can accept appending the given number of bytes.
+     */
+    canAppendMore(size: number): Promise<boolean>;
+}
+/**
+ * Convenience type for buffers capable of both read and write operations.
+ */
+export type IReadableAndWritableBuffer = IReadableBuffer & IWritableBuffer;

package/esm/serialization/buffers/buffer.js

@@ -0,0 +1 @@
+export {};