@sachitv/avro-typescript 0.4.0

package/esm/schemas/logical/decimal_logical_type.d.ts

@@ -0,0 +1,49 @@
+import { BytesType } from "../primitive/bytes_type.js";
+import { FixedType } from "../complex/fixed_type.js";
+import { LogicalType } from "./logical_type.js";
+import type { JSONType } from "../type.js";
+interface DecimalParams {
+    precision: number;
+    scale?: number;
+}
+/**
+ * Decimal logical type.
+ */
+export declare class DecimalLogicalType extends LogicalType<bigint, Uint8Array> {
+    #private;
+    /**
+     * Creates a new DecimalLogicalType.
+     * @param underlying The underlying bytes or fixed type.
+     * @param params The precision and scale parameters.
+     */
+    constructor(underlying: BytesType | FixedType, params: DecimalParams);
+    /**
+     * Gets the precision of the decimal.
+     */
+    getPrecision(): number;
+    /**
+     * Gets the scale of the decimal.
+     */
+    getScale(): number;
+    /**
+     * Checks if a writer schema can be read by this logical type.
+     */
+    protected canReadFromLogical(writer: LogicalType<unknown, unknown>): boolean;
+    /**
+     * Checks if the given value is a bigint representing a decimal.
+     */
+    protected isInstance(value: unknown): value is bigint;
+    /**
+     * Converts a bigint decimal value to its underlying byte representation.
+     */
+    protected toUnderlying(value: bigint): Uint8Array;
+    /**
+     * Converts an underlying byte array to a bigint decimal value.
+     */
+    protected fromUnderlying(value: Uint8Array): bigint;
+    /**
+     * Returns the JSON representation of this decimal logical type.
+     */
+    toJSON(): JSONType;
+}
+export {};

package/esm/schemas/logical/decimal_logical_type.js

@@ -0,0 +1,145 @@
+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 _DecimalLogicalType_precision, _DecimalLogicalType_scale, _DecimalLogicalType_fixedSize;
+import { BytesType } from "../primitive/bytes_type.js";
+import { FixedType } from "../complex/fixed_type.js";
+import { withLogicalTypeJSON } from "./logical_type.js";
+import { LogicalType } from "./logical_type.js";
+/**
+ * Decimal logical type.
+ */
+export class DecimalLogicalType extends LogicalType {
+    /**
+     * Creates a new DecimalLogicalType.
+     * @param underlying The underlying bytes or fixed type.
+     * @param params The precision and scale parameters.
+     */
+    constructor(underlying, params) {
+        super(underlying);
+        _DecimalLogicalType_precision.set(this, void 0);
+        _DecimalLogicalType_scale.set(this, void 0);
+        _DecimalLogicalType_fixedSize.set(this, void 0);
+        if (!(underlying instanceof BytesType || underlying instanceof FixedType)) {
+            throw new Error("Decimal logical type requires bytes or fixed underlying type.");
+        }
+        const precision = params.precision;
+        if (!Number.isInteger(precision) || precision <= 0) {
+            throw new Error("Decimal logical type requires a positive precision.");
+        }
+        const scale = params.scale ?? 0;
+        if (!Number.isInteger(scale) || scale < 0 || scale > precision) {
+            throw new Error("Decimal logical type requires a valid scale (0 <= scale <= precision).");
+        }
+        if (underlying instanceof FixedType) {
+            const size = underlying.getSize();
+            const maxPrecision = Math.floor(Math.log10(2) * (8 * size - 1));
+            if (precision > maxPrecision) {
+                throw new Error("Decimal precision exceeds maximum for fixed size.");
+            }
+            __classPrivateFieldSet(this, _DecimalLogicalType_fixedSize, size, "f");
+        }
+        __classPrivateFieldSet(this, _DecimalLogicalType_precision, precision, "f");
+        __classPrivateFieldSet(this, _DecimalLogicalType_scale, scale, "f");
+    }
+    /**
+     * Gets the precision of the decimal.
+     */
+    getPrecision() {
+        return __classPrivateFieldGet(this, _DecimalLogicalType_precision, "f");
+    }
+    /**
+     * Gets the scale of the decimal.
+     */
+    getScale() {
+        return __classPrivateFieldGet(this, _DecimalLogicalType_scale, "f");
+    }
+    /**
+     * Checks if a writer schema can be read by this logical type.
+     */
+    canReadFromLogical(writer) {
+        return writer instanceof DecimalLogicalType &&
+            __classPrivateFieldGet(writer, _DecimalLogicalType_precision, "f") === __classPrivateFieldGet(this, _DecimalLogicalType_precision, "f") &&
+            __classPrivateFieldGet(writer, _DecimalLogicalType_scale, "f") === __classPrivateFieldGet(this, _DecimalLogicalType_scale, "f");
+    }
+    /**
+     * Checks if the given value is a bigint representing a decimal.
+     */
+    isInstance(value) {
+        return typeof value === "bigint";
+    }
+    /**
+     * Converts a bigint decimal value to its underlying byte representation.
+     */
+    toUnderlying(value) {
+        const digits = value < 0n
+            ? (-value).toString().length
+            : value.toString().length;
+        if (digits > __classPrivateFieldGet(this, _DecimalLogicalType_precision, "f")) {
+            throw new Error(`Decimal value: ${value} exceeds declared precision: ${__classPrivateFieldGet(this, _DecimalLogicalType_precision, "f")}`);
+        }
+        const size = __classPrivateFieldGet(this, _DecimalLogicalType_fixedSize, "f");
+        // Constructor already enforced precision <= max for the fixed size, so every
+        // value that passes the precision check fits within `size` bytes.
+        const byteLength = size ?? minimalBytesForValue(value);
+        return encodeBigInt(value, byteLength);
+    }
+    /**
+     * Converts an underlying byte array to a bigint decimal value.
+     */
+    fromUnderlying(value) {
+        return decodeBigInt(value);
+    }
+    /**
+     * Returns the JSON representation of this decimal logical type.
+     */
+    toJSON() {
+        const extras = {
+            precision: __classPrivateFieldGet(this, _DecimalLogicalType_precision, "f"),
+        };
+        if (__classPrivateFieldGet(this, _DecimalLogicalType_scale, "f") !== 0) {
+            extras.scale = __classPrivateFieldGet(this, _DecimalLogicalType_scale, "f");
+        }
+        return withLogicalTypeJSON(this.getUnderlyingType().toJSON(), "decimal", extras);
+    }
+}
+_DecimalLogicalType_precision = new WeakMap(), _DecimalLogicalType_scale = new WeakMap(), _DecimalLogicalType_fixedSize = new WeakMap();
+function minimalBytesForValue(value) {
+    let bytes = 1;
+    while (value < -(1n << BigInt(bytes * 8 - 1)) ||
+        value >= (1n << BigInt(bytes * 8 - 1))) {
+        bytes++;
+    }
+    return bytes;
+}
+function encodeBigInt(value, size) {
+    let twos = BigInt.asUintN(size * 8, value);
+    const result = new Uint8Array(size);
+    for (let i = size - 1; i >= 0; i--) {
+        result[i] = Number(twos & 0xffn);
+        twos >>= 8n;
+    }
+    return result;
+}
+function decodeBigInt(bytes) {
+    if (bytes.length === 0) {
+        return 0n;
+    }
+    let value = 0n;
+    for (const byte of bytes) {
+        value = (value << 8n) | BigInt(byte);
+    }
+    if (bytes[0] & 0x80) {
+        const max = 1n << BigInt(bytes.length * 8);
+        value -= max;
+    }
+    return value;
+}

package/esm/schemas/logical/duration_logical_type.d.ts

@@ -0,0 +1,66 @@
+import type { FixedType } from "../complex/fixed_type.js";
+import { type LogicalType, NamedLogicalType } from "./logical_type.js";
+import type { JSONType } from "../type.js";
+/**
+ * Represents a duration value with months, days, and milliseconds.
+ */
+export interface DurationValue {
+    /** Number of months. */
+    months: number;
+    /** Number of days. */
+    days: number;
+    /** Number of milliseconds. */
+    millis: number;
+}
+/**
+ * Logical type for `duration`.
+ * Represents a duration of time.
+ */
+export declare class DurationLogicalType extends NamedLogicalType<DurationValue, Uint8Array> {
+    /**
+     * Creates a new DurationLogicalType.
+     * @param underlying The underlying fixed type (must be 12 bytes).
+     */
+    constructor(underlying: FixedType);
+    /**
+     * Checks if this logical type can read from the given writer logical type.
+     * @param writer The writer logical type.
+     * @returns True if compatible.
+     */
+    protected canReadFromLogical(writer: LogicalType<unknown, unknown>): boolean;
+    /**
+     * Checks if the value is an instance of DurationValue.
+     * @param value The value to check.
+     * @returns True if the value is a DurationValue.
+     */
+    protected isInstance(value: unknown): value is DurationValue;
+    /**
+     * Converts the logical DurationValue to its underlying Uint8Array representation.
+     * @param value The DurationValue to convert.
+     * @returns The Uint8Array representation.
+     */
+    protected toUnderlying(value: DurationValue): Uint8Array;
+    /**
+     * Converts the underlying Uint8Array to a DurationValue.
+     * @param value The underlying bytes (must be 12 bytes).
+     * @returns The duration value.
+     */
+    protected fromUnderlying(value: Uint8Array): DurationValue;
+    /**
+     * Compares two DurationValue instances lexicographically.
+     * @param a The first duration value.
+     * @param b The second duration value.
+     * @returns -1 if a < b, 0 if equal, 1 if a > b.
+     */
+    compare(a: DurationValue, b: DurationValue): number;
+    /**
+     * Generates a random DurationValue.
+     * @returns A random duration value.
+     */
+    random(): DurationValue;
+    /**
+     * Returns the JSON representation of this type.
+     * @returns The JSON type.
+     */
+    toJSON(): JSONType;
+}

package/esm/schemas/logical/duration_logical_type.js

@@ -0,0 +1,112 @@
+import { NamedLogicalType, withLogicalTypeJSON, } from "./logical_type.js";
+const MAX_UINT32 = 0xffffffff;
+/**
+ * Logical type for `duration`.
+ * Represents a duration of time.
+ */
+export class DurationLogicalType extends NamedLogicalType {
+    /**
+     * Creates a new DurationLogicalType.
+     * @param underlying The underlying fixed type (must be 12 bytes).
+     */
+    constructor(underlying) {
+        super(underlying);
+        if (underlying.getSize() !== 12) {
+            throw new Error("Duration logical type requires fixed size of 12 bytes.");
+        }
+    }
+    /**
+     * Checks if this logical type can read from the given writer logical type.
+     * @param writer The writer logical type.
+     * @returns True if compatible.
+     */
+    canReadFromLogical(writer) {
+        return writer instanceof DurationLogicalType;
+    }
+    /**
+     * Checks if the value is an instance of DurationValue.
+     * @param value The value to check.
+     * @returns True if the value is a DurationValue.
+     */
+    isInstance(value) {
+        return isDurationValue(value);
+    }
+    /**
+     * Converts the logical DurationValue to its underlying Uint8Array representation.
+     * @param value The DurationValue to convert.
+     * @returns The Uint8Array representation.
+     */
+    toUnderlying(value) {
+        // The value is always valid here since isInstance ensures it.
+        const buffer = new ArrayBuffer(12);
+        const view = new DataView(buffer);
+        view.setUint32(0, value.months, true);
+        view.setUint32(4, value.days, true);
+        view.setUint32(8, value.millis, true);
+        return new Uint8Array(buffer);
+    }
+    /**
+     * Converts the underlying Uint8Array to a DurationValue.
+     * @param value The underlying bytes (must be 12 bytes).
+     * @returns The duration value.
+     */
+    fromUnderlying(value) {
+        if (value.length !== 12) {
+            throw new Error("Duration bytes must be 12 bytes long.");
+        }
+        const view = new DataView(value.buffer, value.byteOffset, value.byteLength);
+        return {
+            months: view.getUint32(0, true),
+            days: view.getUint32(4, true),
+            millis: view.getUint32(8, true),
+        };
+    }
+    /**
+     * Compares two DurationValue instances lexicographically.
+     * @param a The first duration value.
+     * @param b The second duration value.
+     * @returns -1 if a < b, 0 if equal, 1 if a > b.
+     */
+    compare(a, b) {
+        if (a.months !== b.months) {
+            return a.months < b.months ? -1 : 1;
+        }
+        if (a.days !== b.days) {
+            return a.days < b.days ? -1 : 1;
+        }
+        if (a.millis !== b.millis) {
+            return a.millis < b.millis ? -1 : 1;
+        }
+        return 0;
+    }
+    /**
+     * Generates a random DurationValue.
+     * @returns A random duration value.
+     */
+    random() {
+        return {
+            months: Math.floor(Math.random() * 1200),
+            days: Math.floor(Math.random() * 365),
+            millis: Math.floor(Math.random() * 86400000),
+        };
+    }
+    /**
+     * Returns the JSON representation of this type.
+     * @returns The JSON type.
+     */
+    toJSON() {
+        return withLogicalTypeJSON(this.getUnderlyingType().toJSON(), "duration");
+    }
+}
+function isDurationValue(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const maybe = value;
+    return isUint32(maybe.months) && isUint32(maybe.days) &&
+        isUint32(maybe.millis);
+}
+function isUint32(value) {
+    return typeof value === "number" && Number.isInteger(value) &&
+        value >= 0 && value <= MAX_UINT32;
+}

package/esm/schemas/logical/logical_type.d.ts

@@ -0,0 +1,138 @@
+import type { ReadableTapLike, WritableTapLike } from "../../serialization/tap.js";
+import { Resolver } from "../resolver.js";
+import type { NamedType } from "../complex/named_type.js";
+import { Type } from "../type.js";
+import type { JSONType } from "../type.js";
+import { type ErrorHook } from "../error.js";
+/**
+ * Base class for Avro logical types that wrap an underlying physical type
+ * while exposing a richer TypeScript representation.
+ */
+export declare abstract class LogicalType<TValue, TUnderlying> extends Type<TValue> {
+    /** The underlying type that this logical type wraps. */
+    protected readonly underlyingType: Type<TUnderlying>;
+    /**
+     * Constructs a new LogicalType.
+     * @param underlyingType - The underlying type to wrap.
+     */
+    protected constructor(underlyingType: Type<TUnderlying>);
+    /**
+     * Gets the underlying type that this logical type wraps.
+     */
+    getUnderlyingType(): Type<TUnderlying>;
+    /**
+     * Checks if a value is an instance of the logical type's value.
+     */
+    protected abstract isInstance(value: unknown): value is TValue;
+    /**
+     * Converts the logical value to its underlying representation.
+     */
+    protected abstract toUnderlying(value: TValue): TUnderlying;
+    /**
+     * Converts the underlying representation to the logical value.
+     */
+    protected abstract fromUnderlying(value: TUnderlying): TValue;
+    /**
+     * Converts a value from the underlying type to the logical type value.
+     * @param value The underlying value.
+     */
+    convertFromUnderlying(value: TUnderlying): TValue;
+    /**
+     * Determines if this logical type is compatible with the writer logical type for reading.
+     */
+    protected canReadFromLogical(_writer: LogicalType<unknown, unknown>): boolean;
+    /**
+     * Serializes the logical value to an ArrayBuffer.
+     * @param value The logical value to serialize.
+     */
+    toBuffer(value: TValue): Promise<ArrayBuffer>;
+    /**
+     * Deserializes a logical value from an ArrayBuffer.
+     * @param buffer The buffer to deserialize from.
+     */
+    fromBuffer(buffer: ArrayBuffer): Promise<TValue>;
+    /**
+     * Checks if the given value is valid for this type.
+     * @param value The value to validate.
+     * @param opts Optional validation options.
+     */
+    isValid(value: unknown, opts?: {
+        errorHook?: ErrorHook;
+    }): boolean;
+    /**
+     * Validates the value against this type, reporting errors via the hook if provided.
+     * @param value The value to check.
+     * @param errorHook Optional hook for reporting validation errors.
+     * @param path The path to the value in the schema.
+     */
+    check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /**
+     * Clones a value, ensuring it is valid for this type.
+     */
+    cloneFromValue(value: unknown): TValue;
+    /**
+     * Compares two values by comparing their underlying representations.
+     */
+    compare(val1: TValue, val2: TValue): number;
+    /**
+     * Generates a random value by generating a random underlying value and converting it.
+     */
+    random(): TValue;
+    /**
+     * Writes the value to the tap by writing the underlying value.
+     */
+    write(tap: WritableTapLike, value: TValue): Promise<void>;
+    /** Reads the value from the tap. */
+    read(tap: ReadableTapLike): Promise<TValue>;
+    /** Skips the value in the tap. */
+    skip(tap: ReadableTapLike): Promise<void>;
+    /** Matches the value in the taps. */
+    match(tap1: ReadableTapLike, tap2: ReadableTapLike): Promise<number>;
+    /**
+     * Creates a resolver for reading from the writer type, handling logical types specially.
+     */
+    createResolver(writerType: Type): Resolver;
+    /**
+     * Ensures the value is valid for this logical type.
+     * @param value The value to validate.
+     * @param path The path for error reporting.
+     */
+    protected ensureValid(value: TValue, path: string[]): void;
+    /**
+     * Returns the JSON representation of this logical type.
+     */
+    abstract toJSON(): JSONType;
+}
+/**
+ * Logical type variant for named Avro schemas (record, enum, fixed) that keeps
+ * track of the fully qualified name and aliases of the underlying type.
+ */
+/**
+ * Logical type variant for named Avro schemas (record, enum, fixed) that keeps
+ * track of the fully qualified name and aliases of the underlying type.
+ */
+export declare abstract class NamedLogicalType<TValue, TUnderlying> extends LogicalType<TValue, TUnderlying> {
+    /** The underlying named type. */
+    protected readonly namedType: NamedType<TUnderlying>;
+    /**
+     * Creates a new NamedLogicalType.
+     * @param namedType The underlying named type.
+     */
+    protected constructor(namedType: NamedType<TUnderlying>);
+    /**
+     * Gets the full name of the underlying type.
+     */
+    getFullName(): string;
+    /**
+     * Gets the namespace of the underlying type.
+     */
+    getNamespace(): string;
+    /**
+     * Gets the aliases of the underlying type.
+     */
+    getAliases(): string[];
+}
+/**
+ * Helper to attach a logicalType annotation to an underlying Avro schema JSON.
+ */
+export declare function withLogicalTypeJSON(underlying: JSONType, logicalType: string, extras?: Record<string, unknown>): JSONType;