@sachitv/avro-typescript 0.4.0

package/esm/schemas/primitive/long_type.js

@@ -0,0 +1,95 @@
+import { WritableTap, } from "../../serialization/tap.js";
+import { PrimitiveType } from "./primitive_type.js";
+import { Resolver } from "../resolver.js";
+import { IntType } from "./int_type.js";
+import { throwInvalidError } from "../error.js";
+import { calculateVarintSize } from "../../internal/varint.js";
+const MIN_LONG = -(1n << 63n);
+const MAX_LONG = (1n << 63n) - 1n;
+/**
+ * Long type (64-bit).
+ */
+export class LongType extends PrimitiveType {
+    /** Checks if the value is a valid long. */
+    check(value, errorHook, path = []) {
+        const isValid = typeof value === "bigint" && value >= MIN_LONG &&
+            value <= MAX_LONG;
+        if (!isValid && errorHook) {
+            errorHook(path, value, this);
+        }
+        return isValid;
+    }
+    /** Reads a long value from the tap. */
+    async read(tap) {
+        return await tap.readLong();
+    }
+    /** Writes a long value to the tap. */
+    async write(tap, value) {
+        if (!this.check(value)) {
+            throwInvalidError([], value, this);
+        }
+        await tap.writeLong(value);
+    }
+    /** Skips a long value in the tap. */
+    async skip(tap) {
+        await tap.skipLong();
+    }
+    /** Converts a bigint value to its buffer representation. */
+    async toBuffer(value) {
+        this.check(value, throwInvalidError, []);
+        // For long, allocate exact size based on value
+        const size = calculateVarintSize(value);
+        const buf = new ArrayBuffer(size);
+        const tap = new WritableTap(buf);
+        await this.write(tap, value);
+        return buf;
+    }
+    /**
+     * Compares two long values.
+     */
+    compare(val1, val2) {
+        return val1 < val2 ? -1 : val1 > val2 ? 1 : 0;
+    }
+    /**
+     * Generates a random long value.
+     */
+    random() {
+        return BigInt(Math.floor(Math.random() * 1000));
+    }
+    /** Clones and validates a value as a bigint. */
+    cloneFromValue(value) {
+        if (typeof value === "bigint") {
+            this.check(value, throwInvalidError, []);
+            return value;
+        }
+        if (typeof value === "number" && Number.isInteger(value)) {
+            const candidate = BigInt(value);
+            this.check(candidate, throwInvalidError, []);
+            return candidate;
+        }
+        throwInvalidError([], value, this);
+    }
+    /** Creates a resolver for reading from the writer type. */
+    createResolver(writerType) {
+        if (writerType instanceof IntType) {
+            // Long can promote from int (32-bit to 64-bit)
+            return new class extends Resolver {
+                async read(tap) {
+                    const intValue = await tap.readInt();
+                    return BigInt(intValue);
+                }
+            }(this);
+        }
+        else {
+            return super.createResolver(writerType);
+        }
+    }
+    /** Returns the JSON representation of the type. */
+    toJSON() {
+        return "long";
+    }
+    /** Compares two taps for long equality. */
+    async match(tap1, tap2) {
+        return await tap1.matchLong(tap2);
+    }
+}

package/esm/schemas/primitive/null_type.d.ts

@@ -0,0 +1,45 @@
+import type { ReadableTapLike, WritableTapLike } from "../../serialization/tap.js";
+import { FixedSizeBaseType } from "./fixed_size_base_type.js";
+import type { JSONType } from "../type.js";
+import { type ErrorHook } from "../error.js";
+/**
+ * Null type.
+ */
+export declare class NullType extends FixedSizeBaseType<null> {
+    /**
+     * Checks if the value is null.
+     */
+    check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /**
+     * Reads a null value from the tap.
+     */
+    read(_tap: ReadableTapLike): Promise<null>;
+    /**
+     * Writes a null value to the tap.
+     */
+    write(_tap: WritableTapLike, value: null): Promise<void>;
+    /**
+     * Skips a null value in the tap.
+     */
+    skip(_tap: ReadableTapLike): Promise<void>;
+    /**
+     * Gets the size in bytes.
+     */
+    sizeBytes(): number;
+    /**
+     * Clones a null value from the given value.
+     */
+    cloneFromValue(value: unknown): null;
+    /**
+     * Compares two null values.
+     */
+    compare(_val1: null, _val2: null): number;
+    /**
+     * Generates a random null value.
+     */
+    random(): null;
+    /** Returns the JSON representation of the type. */
+    toJSON(): JSONType;
+    /** Compares two null values in the taps. */
+    match(_tap1: ReadableTapLike, _tap2: ReadableTapLike): Promise<number>;
+}

package/esm/schemas/primitive/null_type.js

@@ -0,0 +1,71 @@
+import { FixedSizeBaseType } from "./fixed_size_base_type.js";
+import { throwInvalidError } from "../error.js";
+/**
+ * Null type.
+ */
+export class NullType extends FixedSizeBaseType {
+    /**
+     * Checks if the value is null.
+     */
+    check(value, errorHook, path = []) {
+        const isValid = value === null;
+        if (!isValid && errorHook) {
+            errorHook(path, value, this);
+        }
+        return isValid;
+    }
+    /**
+     * Reads a null value from the tap.
+     */
+    async read(_tap) {
+        return await Promise.resolve(null);
+    }
+    /**
+     * Writes a null value to the tap.
+     */
+    async write(_tap, value) {
+        if (value !== null) {
+            throwInvalidError([], value, this);
+        }
+        await Promise.resolve();
+    }
+    /**
+     * Skips a null value in the tap.
+     */
+    async skip(_tap) {
+        // Null takes no space
+    }
+    /**
+     * Gets the size in bytes.
+     */
+    sizeBytes() {
+        return 0; // Null takes no space
+    }
+    /**
+     * Clones a null value from the given value.
+     */
+    cloneFromValue(value) {
+        this.check(value, throwInvalidError, []);
+        return value;
+    }
+    /**
+     * Compares two null values.
+     */
+    compare(_val1, _val2) {
+        return 0;
+    }
+    /**
+     * Generates a random null value.
+     */
+    random() {
+        return null;
+    }
+    /** Returns the JSON representation of the type. */
+    toJSON() {
+        return "null";
+    }
+    /** Compares two null values in the taps. */
+    async match(_tap1, _tap2) {
+        return await Promise.resolve(0);
+    }
+}

package/esm/schemas/primitive/primitive_type.d.ts

@@ -0,0 +1,17 @@
+import { BaseType } from "../base_type.js";
+/**
+ * Abstract base class for primitive Avro types.
+ */
+export declare abstract class PrimitiveType<T = unknown> extends BaseType<T> {
+    /**
+     * Clones a primitive value (primitives are immutable).
+     */
+    /**
+     * Clones a primitive value.
+     */
+    cloneFromValue(value: unknown): T;
+    /**
+     * Compares two primitive values.
+     */
+    compare(val1: T, val2: T): number;
+}

package/esm/schemas/primitive/primitive_type.js

@@ -0,0 +1,27 @@
+import { BaseType } from "../base_type.js";
+import { throwInvalidError } from "../error.js";
+/**
+ * Abstract base class for primitive Avro types.
+ */
+export class PrimitiveType extends BaseType {
+    /**
+     * Clones a primitive value (primitives are immutable).
+     */
+    /**
+     * Clones a primitive value.
+     */
+    cloneFromValue(value) {
+        this.check(value, throwInvalidError, []);
+        return value;
+    }
+    /**
+     * Compares two primitive values.
+     */
+    compare(val1, val2) {
+        if (val1 < val2)
+            return -1;
+        if (val1 > val2)
+            return 1;
+        return 0;
+    }
+}

package/esm/schemas/primitive/string_type.d.ts

@@ -0,0 +1,34 @@
+import { type ReadableTapLike, type WritableTapLike } from "../../serialization/tap.js";
+import { PrimitiveType } from "./primitive_type.js";
+import type { JSONType, Type } from "../type.js";
+import { Resolver } from "../resolver.js";
+import { type ErrorHook } from "../error.js";
+/**
+ * String type.
+ */
+export declare class StringType extends PrimitiveType<string> {
+    /** Checks if the value is a valid string. */
+    check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /** Converts a string value to its Avro-encoded buffer representation. */
+    toBuffer(value: string): Promise<ArrayBuffer>;
+    /** Reads a string value from the tap. */
+    read(tap: ReadableTapLike): Promise<string>;
+    /** Writes a string value to the tap. */
+    write(tap: WritableTapLike, value: string): Promise<void>;
+    /** Skips a string value in the tap. */
+    skip(tap: ReadableTapLike): Promise<void>;
+    /**
+     * Compares two string values.
+     */
+    compare(val1: string, val2: string): number;
+    /**
+     * Generates a random string value.
+     */
+    random(): string;
+    /** Creates a resolver for reading from a writer type. */
+    createResolver(writerType: Type): Resolver;
+    /** Returns the JSON representation of the string type. */
+    toJSON(): JSONType;
+    /** Matches two readable taps for string equality. */
+    match(tap1: ReadableTapLike, tap2: ReadableTapLike): Promise<number>;
+}

package/esm/schemas/primitive/string_type.js

@@ -0,0 +1,81 @@
+import { WritableTap, } from "../../serialization/tap.js";
+import { PrimitiveType } from "./primitive_type.js";
+import { Resolver } from "../resolver.js";
+import { throwInvalidError } from "../error.js";
+import { calculateVarintSize } from "../../internal/varint.js";
+import { decode, encode } from "../../serialization/text_encoding.js";
+/**
+ * String type.
+ */
+export class StringType extends PrimitiveType {
+    /** Checks if the value is a valid string. */
+    check(value, errorHook, path = []) {
+        const isValid = typeof value === "string";
+        if (!isValid && errorHook) {
+            errorHook(path, value, this);
+        }
+        return isValid;
+    }
+    /** Converts a string value to its Avro-encoded buffer representation. */
+    async toBuffer(value) {
+        this.check(value, throwInvalidError, []);
+        const strBytes = encode(value);
+        const lengthSize = calculateVarintSize(strBytes.length);
+        const buf = new ArrayBuffer(lengthSize + strBytes.length);
+        const tap = new WritableTap(buf);
+        await this.write(tap, value);
+        return buf;
+    }
+    /** Reads a string value from the tap. */
+    async read(tap) {
+        return await tap.readString();
+    }
+    /** Writes a string value to the tap. */
+    async write(tap, value) {
+        if (typeof value !== "string") {
+            throwInvalidError([], value, this);
+        }
+        await tap.writeString(value);
+    }
+    /** Skips a string value in the tap. */
+    async skip(tap) {
+        await tap.skipString();
+    }
+    /**
+     * Compares two string values.
+     */
+    compare(val1, val2) {
+        return val1 < val2 ? -1 : val1 > val2 ? 1 : 0;
+    }
+    /**
+     * Generates a random string value.
+     */
+    random() {
+        return Math.random().toString(36).substring(2, 10);
+    }
+    /** Creates a resolver for reading from a writer type. */
+    createResolver(writerType) {
+        if (writerType.toJSON() === "bytes") {
+            // String can promote from bytes. We use an anonymous class here to avoid a
+            // cyclic dependency between this file and the bytes type file.
+            return new class extends Resolver {
+                async read(tap) {
+                    const bytes = await tap.readBytes();
+                    // Convert bytes to string (assuming UTF-8)
+                    return decode(bytes);
+                }
+            }(this);
+        }
+        else {
+            return super.createResolver(writerType);
+        }
+    }
+    /** Returns the JSON representation of the string type. */
+    toJSON() {
+        return "string";
+    }
+    /** Matches two readable taps for string equality. */
+    async match(tap1, tap2) {
+        return await tap1.matchString(tap2);
+    }
+}

package/esm/schemas/resolver.d.ts

@@ -0,0 +1,25 @@
+import type { ReadableTapLike } from "../serialization/tap.js";
+import type { Type } from "./type.js";
+/**
+ * Base resolver for schema evolution, allowing reading data written with one schema
+ * using a different but compatible reader schema.
+ */
+/**
+ * Abstract base class for schema resolvers.
+ * Resolvers handle reading data written by a writer schema into a reader schema,
+ * potentially performing conversions or handling evolution.
+ */
+export declare abstract class Resolver<T = unknown> {
+    /** The type used for reading. */
+    protected readerType: Type<T>;
+    /**
+     * Creates a new Resolver.
+     * @param readerType The reader schema type.
+     */
+    constructor(readerType: Type<T>);
+    /**
+     * Reads a value from the tap using the resolution logic.
+     * @param tap The tap to read from.
+     */
+    abstract read(tap: ReadableTapLike): Promise<T>;
+}

package/esm/schemas/resolver.js

@@ -0,0 +1,25 @@
+/**
+ * Base resolver for schema evolution, allowing reading data written with one schema
+ * using a different but compatible reader schema.
+ */
+/**
+ * Abstract base class for schema resolvers.
+ * Resolvers handle reading data written by a writer schema into a reader schema,
+ * potentially performing conversions or handling evolution.
+ */
+export class Resolver {
+    /**
+     * Creates a new Resolver.
+     * @param readerType The reader schema type.
+     */
+    constructor(readerType) {
+        /** The type used for reading. */
+        Object.defineProperty(this, "readerType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.readerType = readerType;
+    }
+}

package/esm/schemas/type.d.ts

@@ -0,0 +1,101 @@
+import type { ReadableTapLike, WritableTapLike } from "../serialization/tap.js";
+import type { Resolver } from "./resolver.js";
+import type { ErrorHook } from "./error.js";
+/**
+ * Options for validation, including an optional error hook.
+ */
+export type IsValidOptions = {
+    errorHook?: ErrorHook;
+};
+/**
+ * Represents a JSON value used in Avro schema definitions.
+ */
+export type JSONType = string | number | boolean | null | {
+    [key: string]: JSONType;
+} | JSONType[];
+/**
+ * Pure abstract base class for all Avro schema types.
+ * Provides the common interface for serialization, deserialization, validation, and cloning.
+ */
+export declare abstract class Type<T = unknown> {
+    /**
+     * Serializes a value into an ArrayBuffer using the schema.
+     * @param value The value to serialize.
+     * @returns The serialized ArrayBuffer.
+     */
+    abstract toBuffer(value: T): Promise<ArrayBuffer>;
+    /**
+     * Deserializes an ArrayBuffer into a value using the schema.
+     * @param buffer The ArrayBuffer to deserialize.
+     * @returns The deserialized value.
+     */
+    abstract fromBuffer(buffer: ArrayBuffer): Promise<T>;
+    /**
+     * Validates if a value conforms to the schema.
+     * @param value The value to validate.
+     * @param opts Optional validation options.
+     * @returns True if valid, false otherwise.
+     */
+    abstract isValid(value: unknown, opts?: IsValidOptions): boolean;
+    /**
+     * Creates a deep clone of the value.
+     * @param value The value to clone.
+     * @returns The cloned value.
+     */
+    abstract cloneFromValue(value: unknown): T;
+    /**
+     * Creates a resolver for schema evolution from a writer type to this reader type.
+     * @param writerType The writer schema type.
+     * @returns A resolver for reading the writer type as this type.
+     */
+    abstract createResolver(writerType: Type): Resolver;
+    /**
+     * Writes a value to the tap. Must be implemented by subclasses.
+     * @param tap The tap to write to.
+     * @param value The value to write.
+     */
+    abstract write(tap: WritableTapLike, value: T): Promise<void>;
+    /**
+     * Reads a value from the tap. Must be implemented by subclasses.
+     * @param tap The tap to read from.
+     * @returns The read value.
+     */
+    abstract read(tap: ReadableTapLike): Promise<T>;
+    /**
+     * Skips a value in the tap. Must be implemented by subclasses.
+     * @param tap The tap to skip from.
+     */
+    abstract skip(tap: ReadableTapLike): Promise<void>;
+    /**
+     * Checks if a value is valid according to the schema. Must be implemented by subclasses.
+     * @param value The value to check.
+     * @param errorHook Optional error callback.
+     * @param path Current path in the schema for error reporting.
+     * @returns True if valid.
+     */
+    abstract check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /**
+     * Compares two values. Must be implemented by subclasses.
+     * @param val1 First value.
+     * @param val2 Second value.
+     * @returns -1 if val1 < val2, 0 if equal, 1 if val1 > val2.
+     */
+    abstract compare(val1: T, val2: T): number;
+    /**
+     * Generates a random value. Must be implemented by subclasses.
+     * @returns A random value of this type.
+     */
+    abstract random(): T;
+    /**
+     * Returns the JSON schema representation.
+     * @returns The JSON representation as JSONType.
+     */
+    abstract toJSON(): JSONType;
+    /**
+     * Compares two encoded buffers. Must be implemented by subclasses.
+     * @param tap1 The first tap.
+     * @param tap2 The second tap.
+     * @returns -1 if tap1 < tap2, 0 if equal, 1 if tap1 > tap2.
+     */
+    abstract match(tap1: ReadableTapLike, tap2: ReadableTapLike): Promise<number>;
+}

package/esm/schemas/type.js

@@ -0,0 +1,6 @@
+/**
+ * Pure abstract base class for all Avro schema types.
+ * Provides the common interface for serialization, deserialization, validation, and cloning.
+ */
+export class Type {
+}

package/esm/serialization/avro_constants.d.ts

@@ -0,0 +1,13 @@
+import type { Type } from "../schemas/type.js";
+/**
+ * Avro schema definition for the object container file header section.
+ */
+export declare const HEADER_TYPE: Type;
+/**
+ * Avro schema definition for individual data blocks within a container file.
+ */
+export declare const BLOCK_TYPE: Type;
+/**
+ * Magic bytes that prefix every Avro object container file (`Obj\x01`).
+ */
+export declare const MAGIC_BYTES: Uint8Array;

package/esm/serialization/avro_constants.js

@@ -0,0 +1,29 @@
+import { createType } from "../type/create_type.js";
+/**
+ * Avro schema definition for the object container file header section.
+ */
+export const HEADER_TYPE = createType({
+    type: "record",
+    name: "org.apache.avro.file.Header",
+    fields: [
+        { name: "magic", type: { type: "fixed", name: "Magic", size: 4 } },
+        { name: "meta", type: { type: "map", values: "bytes" } },
+        { name: "sync", type: { type: "fixed", name: "Sync", size: 16 } },
+    ],
+});
+/**
+ * Avro schema definition for individual data blocks within a container file.
+ */
+export const BLOCK_TYPE = createType({
+    type: "record",
+    name: "org.apache.avro.file.Block",
+    fields: [
+        { name: "count", type: "long" },
+        { name: "data", type: "bytes" },
+        { name: "sync", type: { type: "fixed", name: "Sync", size: 16 } },
+    ],
+});
+/**
+ * Magic bytes that prefix every Avro object container file (`Obj\x01`).
+ */
+export const MAGIC_BYTES = new Uint8Array([0x4F, 0x62, 0x6A, 0x01]); // 'Obj\x01'

package/esm/serialization/avro_file_parser.d.ts

@@ -0,0 +1,68 @@
+import { Type } from "../schemas/type.js";
+import type { IReadableBuffer } from "./buffers/buffer.js";
+import type { Decoder, DecoderRegistry } from "./decoders/decoder.js";
+import { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES } from "./avro_constants.js";
+export type { Decoder, DecoderRegistry };
+export { BLOCK_TYPE, HEADER_TYPE, MAGIC_BYTES };
+/**
+ * Internal interface for Avro file header information.
+ */
+export interface AvroHeader {
+    /** The magic bytes that identify the file as an Avro object container file, typically "Obj\x01". */
+    magic: Uint8Array;
+    /** A map of metadata key-value pairs containing schema, codec, and other file information. */
+    meta: Map<string, Uint8Array>;
+    /** A 16-byte synchronization marker used to separate data blocks in the file. */
+    sync: Uint8Array;
+    /** The parsed Avro schema type derived from the schema in the metadata. */
+    schemaType: Type;
+}
+/**
+ * Public interface for parsed Avro file header with proper typing.
+ */
+export interface ParsedAvroHeader {
+    /** The magic bytes that identify the file as an Avro object container file, typically "Obj\x01". */
+    magic: Uint8Array;
+    /** A map of metadata key-value pairs containing schema, codec, and other file information. */
+    meta: Map<string, Uint8Array>;
+    /** A 16-byte synchronization marker used to separate data blocks in the file. */
+    sync: Uint8Array;
+}
+/**
+ * Internal parser for Avro object container files.
+ * Handles header parsing and record iteration.
+ */
+export interface AvroFileParserOptions {
+    /** Optional reader schema used to resolve records written with a different schema. */
+    readerSchema?: unknown;
+    /** Custom codec decoders. Cannot include "null" or "deflate" as they are built-in. */
+    decoders?: DecoderRegistry;
+}
+/**
+ * Parser for Avro object container files that reads headers, resolves schemas,
+ * and streams decoded records from readable buffers.
+ */
+export declare class AvroFileParser {
+    #private;
+    /**
+     * Creates a new AvroFileParser.
+     *
+     * @param buffer The readable buffer containing Avro data.
+     * @param options Configuration options for parsing.
+     */
+    constructor(buffer: IReadableBuffer, options?: AvroFileParserOptions);
+    /**
+     * 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.
+     */
+    getHeader(): Promise<ParsedAvroHeader>;
+    /**
+     * 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.
+     */
+    iterRecords(): AsyncIterableIterator<unknown>;
+}