@sachitv/avro-typescript 0.4.0

package/esm/schemas/complex/union_type.d.ts

@@ -0,0 +1,116 @@
+import { BaseType } from "../base_type.js";
+import { Resolver } from "../resolver.js";
+import { type JSONType, Type } from "../type.js";
+import { type ErrorHook } from "../error.js";
+import { type ReadableTapLike, type WritableTapLike } from "../../serialization/tap.js";
+/**
+ * Represents a wrapped value for a union type.
+ */
+export type UnionWrappedValue = Record<string, unknown>;
+/**
+ * Represents a value for a union type, which can be a wrapped value or null.
+ */
+export type UnionValue = UnionWrappedValue | null;
+/**
+ * Parameters for creating a UnionType.
+ */
+export interface UnionTypeParams {
+    /** The types that make up the union. */
+    types: Type[];
+}
+/**
+ * Avro `union` type that supports values conforming to one of multiple schemas.
+ */
+export declare class UnionType extends BaseType<UnionValue> {
+    #private;
+    /**
+     * Creates a new UnionType.
+     * @param params The union type parameters.
+     */
+    constructor(params: UnionTypeParams);
+    /**
+     * Gets the types in this union.
+     */
+    getTypes(): Type[];
+    /**
+     * Checks if the given value conforms to this union type.
+     * For null values, verifies if a null branch exists.
+     * For wrapped values, ensures it's an object with a single key matching a branch name,
+     * and validates the inner value against the corresponding branch type.
+     * @param value The value to check.
+     * @param errorHook Optional error hook for validation errors.
+     * @param path The current path for error reporting.
+     * @returns True if the value is valid, false otherwise.
+     */
+    check(value: unknown, errorHook?: ErrorHook, path?: string[]): boolean;
+    /**
+     * Serializes the union value to the writable tap.
+     * Writes the branch index as a long, followed by the branch value if not null.
+     * @param tap The writable tap to write to.
+     * @param value The union value to serialize.
+     */
+    write(tap: WritableTapLike, value: UnionValue): Promise<void>;
+    /**
+     * Deserializes a union value from the readable tap.
+     * Reads the branch index, and if not null, reads the branch value and wraps it in an object.
+     * @param tap The readable tap to read from.
+     * @returns The deserialized union value.
+     */
+    read(tap: ReadableTapLike): Promise<UnionValue>;
+    /**
+     * Skips over a union value in the readable tap.
+     * Reads the branch index and skips the branch value if not null.
+     * @param tap The readable tap to skip in.
+     */
+    skip(tap: ReadableTapLike): Promise<void>;
+    /**
+     * Converts the union value to an ArrayBuffer.
+     * Calculates the size needed for the index and branch value, then writes them to a new buffer.
+     * @param value The union value to convert.
+     * @returns The ArrayBuffer containing the serialized value.
+     */
+    toBuffer(value: UnionValue): Promise<ArrayBuffer>;
+    /**
+     * Creates a deep clone of the given value as a union value.
+     * Handles null values and wrapped objects by cloning the inner value using the branch type.
+     * @param value The value to clone.
+     * @returns The cloned union value.
+     */
+    cloneFromValue(value: unknown): UnionValue;
+    /**
+     * Compares two union values for ordering.
+     * First compares by branch index; if equal, compares the branch values using the branch type's compare method.
+     * @param val1 The first union value.
+     * @param val2 The second union value.
+     * @returns Negative if val1 < val2, zero if equal, positive if val1 > val2.
+     */
+    compare(val1: UnionValue, val2: UnionValue): number;
+    /**
+     * Generates a random union value.
+     * Selects a random branch and generates a random value for that branch, wrapping it appropriately.
+     * @returns A random union value.
+     */
+    random(): UnionValue;
+    /**
+     * Returns the JSON representation of the union type.
+     * An array of the JSON representations of each branch type.
+     * @returns The JSON type array.
+     */
+    toJSON(): JSONType;
+    /**
+     * Compares two serialized union values from taps for ordering.
+     * Reads the branch indices from both taps; if equal, compares the branch values using the branch type's match method.
+     * @param tap1 The first readable tap.
+     * @param tap2 The second readable tap.
+     * @returns Negative if tap1 < tap2, zero if equal, positive if tap1 > tap2.
+     */
+    match(tap1: ReadableTapLike, tap2: ReadableTapLike): Promise<number>;
+    /**
+     * Creates a resolver for schema evolution from the writer type to this union type.
+     * If the writer is also a union, creates resolvers for each branch.
+     * Otherwise, finds a compatible branch in this union and creates a resolver for it.
+     * @param writerType The writer type to resolve from.
+     * @returns A resolver for the union value.
+     */
+    createResolver(writerType: Type): Resolver<UnionValue>;
+}

package/esm/schemas/complex/union_type.js

@@ -0,0 +1,392 @@
+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 _UnionType_instances, _UnionType_types, _UnionType_branches, _UnionType_indices, _UnionType_resolveBranch, _UnionType_readBranchIndex, _UnionBranchResolver_branch, _UnionBranchResolver_branchResolver, _UnionFromUnionResolver_resolvers;
+import { BaseType } from "../base_type.js";
+import { NamedType } from "./named_type.js";
+import { Resolver } from "../resolver.js";
+import { Type } from "../type.js";
+import { throwInvalidError } from "../error.js";
+import { WritableTap, } from "../../serialization/tap.js";
+import { bigIntToSafeNumber } from "../../serialization/conversion.js";
+import { calculateVarintSize } from "../../internal/varint.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null &&
+        !Array.isArray(value);
+}
+/** @internal */
+/**
+ * Gets the branch name for a given type.
+ * @param type The type to get the name for.
+ * @returns The branch name.
+ * @internal
+ */
+export function getBranchTypeName(type) {
+    if (type instanceof NamedType) {
+        return type.getFullName();
+    }
+    const schema = type.toJSON();
+    if (typeof schema === "string") {
+        return schema;
+    }
+    if (schema && typeof schema === "object") {
+        const maybeType = schema.type;
+        if (typeof maybeType === "string") {
+            return maybeType;
+        }
+    }
+    throw new Error("Unable to determine union branch name.");
+}
+/**
+ * Avro `union` type that supports values conforming to one of multiple schemas.
+ */
+export class UnionType extends BaseType {
+    /**
+     * Creates a new UnionType.
+     * @param params The union type parameters.
+     */
+    constructor(params) {
+        super();
+        _UnionType_instances.add(this);
+        _UnionType_types.set(this, void 0);
+        _UnionType_branches.set(this, void 0);
+        _UnionType_indices.set(this, void 0);
+        const { types } = params;
+        if (!Array.isArray(types)) {
+            throw new Error("UnionType requires an array of branch types.");
+        }
+        if (types.length === 0) {
+            throw new Error("UnionType requires at least one branch type.");
+        }
+        __classPrivateFieldSet(this, _UnionType_types, [], "f");
+        __classPrivateFieldSet(this, _UnionType_branches, [], "f");
+        __classPrivateFieldSet(this, _UnionType_indices, new Map(), "f");
+        types.forEach((type, index) => {
+            if (!(type instanceof Type)) {
+                throw new Error("UnionType branches must be Avro types.");
+            }
+            if (type instanceof UnionType) {
+                throw new Error("Unions cannot be directly nested.");
+            }
+            const name = getBranchTypeName(type);
+            if (__classPrivateFieldGet(this, _UnionType_indices, "f").has(name)) {
+                throw new Error(`Duplicate union branch of type name: ${name}`);
+            }
+            const branch = {
+                type,
+                name,
+                isNull: name === "null",
+            };
+            __classPrivateFieldGet(this, _UnionType_types, "f").push(type);
+            __classPrivateFieldGet(this, _UnionType_branches, "f").push(branch);
+            __classPrivateFieldGet(this, _UnionType_indices, "f").set(name, index);
+        });
+    }
+    /**
+     * Gets the types in this union.
+     */
+    getTypes() {
+        return __classPrivateFieldGet(this, _UnionType_types, "f").slice();
+    }
+    /**
+     * Checks if the given value conforms to this union type.
+     * For null values, verifies if a null branch exists.
+     * For wrapped values, ensures it's an object with a single key matching a branch name,
+     * and validates the inner value against the corresponding branch type.
+     * @param value The value to check.
+     * @param errorHook Optional error hook for validation errors.
+     * @param path The current path for error reporting.
+     * @returns True if the value is valid, false otherwise.
+     */
+    check(value, errorHook, path = []) {
+        if (value === null) {
+            const hasNull = __classPrivateFieldGet(this, _UnionType_indices, "f").has("null");
+            if (!hasNull && errorHook) {
+                errorHook(path.slice(), value, this);
+            }
+            return hasNull;
+        }
+        if (!isPlainObject(value)) {
+            if (errorHook) {
+                errorHook(path.slice(), value, this);
+            }
+            return false;
+        }
+        const keys = Object.keys(value);
+        if (keys.length !== 1) {
+            if (errorHook) {
+                errorHook(path.slice(), value, this);
+            }
+            return false;
+        }
+        const key = keys[0];
+        // Handle the case where the key itself is "null", this should never validate.
+        if (key === "null") {
+            if (errorHook) {
+                errorHook(path.slice(), value, this);
+            }
+            return false;
+        }
+        const branchIndex = __classPrivateFieldGet(this, _UnionType_indices, "f").get(key);
+        if (branchIndex === undefined) {
+            if (errorHook) {
+                errorHook(path.slice(), value, this);
+            }
+            return false;
+        }
+        const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[branchIndex];
+        const branchValue = value[key];
+        const branchPath = errorHook ? [...path, key] : undefined;
+        const isValid = branch.type.check(branchValue, errorHook, branchPath);
+        if (!isValid && errorHook) {
+            // Underlying type already invoked errorHook with extended path.
+            return false;
+        }
+        return isValid;
+    }
+    /**
+     * Serializes the union value to the writable tap.
+     * Writes the branch index as a long, followed by the branch value if not null.
+     * @param tap The writable tap to write to.
+     * @param value The union value to serialize.
+     */
+    async write(tap, value) {
+        const { index, branchValue } = __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_resolveBranch).call(this, value);
+        await tap.writeLong(BigInt(index));
+        if (branchValue !== undefined) {
+            await __classPrivateFieldGet(this, _UnionType_branches, "f")[index].type.write(tap, branchValue);
+        }
+    }
+    /**
+     * Deserializes a union value from the readable tap.
+     * Reads the branch index, and if not null, reads the branch value and wraps it in an object.
+     * @param tap The readable tap to read from.
+     * @returns The deserialized union value.
+     */
+    async read(tap) {
+        const index = await __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_readBranchIndex).call(this, tap);
+        const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[index];
+        if (branch.isNull) {
+            return null;
+        }
+        const branchValue = await branch.type.read(tap);
+        return { [branch.name]: branchValue };
+    }
+    /**
+     * Skips over a union value in the readable tap.
+     * Reads the branch index and skips the branch value if not null.
+     * @param tap The readable tap to skip in.
+     */
+    async skip(tap) {
+        const index = await __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_readBranchIndex).call(this, tap);
+        const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[index];
+        if (!branch.isNull) {
+            await branch.type.skip(tap);
+        }
+    }
+    /**
+     * Converts the union value to an ArrayBuffer.
+     * Calculates the size needed for the index and branch value, then writes them to a new buffer.
+     * @param value The union value to convert.
+     * @returns The ArrayBuffer containing the serialized value.
+     */
+    async toBuffer(value) {
+        const { index, branchValue } = __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_resolveBranch).call(this, value);
+        const indexSize = calculateVarintSize(index);
+        let totalSize = indexSize;
+        let branchBytes;
+        if (branchValue !== undefined) {
+            branchBytes = new Uint8Array(await __classPrivateFieldGet(this, _UnionType_branches, "f")[index].type.toBuffer(branchValue));
+            totalSize += branchBytes.byteLength;
+        }
+        const buffer = new ArrayBuffer(totalSize);
+        const tap = new WritableTap(buffer);
+        await tap.writeLong(BigInt(index));
+        if (branchBytes) {
+            await tap.writeFixed(branchBytes);
+        }
+        return buffer;
+    }
+    /**
+     * Creates a deep clone of the given value as a union value.
+     * Handles null values and wrapped objects by cloning the inner value using the branch type.
+     * @param value The value to clone.
+     * @returns The cloned union value.
+     */
+    cloneFromValue(value) {
+        if (value === null) {
+            if (!__classPrivateFieldGet(this, _UnionType_indices, "f").has("null")) {
+                throw new Error("Cannot clone null for a union without null branch.");
+            }
+            return null;
+        }
+        const { index, branchValue } = __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_resolveBranch).call(this, value);
+        if (branchValue === undefined) {
+            return null;
+        }
+        const cloned = __classPrivateFieldGet(this, _UnionType_branches, "f")[index].type.cloneFromValue(branchValue);
+        return { [__classPrivateFieldGet(this, _UnionType_branches, "f")[index].name]: cloned };
+    }
+    /**
+     * Compares two union values for ordering.
+     * First compares by branch index; if equal, compares the branch values using the branch type's compare method.
+     * @param val1 The first union value.
+     * @param val2 The second union value.
+     * @returns Negative if val1 < val2, zero if equal, positive if val1 > val2.
+     */
+    compare(val1, val2) {
+        const branch1 = __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_resolveBranch).call(this, val1);
+        const branch2 = __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_resolveBranch).call(this, val2);
+        if (branch1.index === branch2.index) {
+            if (branch1.branchValue === undefined) {
+                return 0;
+            }
+            return __classPrivateFieldGet(this, _UnionType_branches, "f")[branch1.index].type.compare(branch1.branchValue, branch2.branchValue);
+        }
+        return branch1.index < branch2.index ? -1 : 1;
+    }
+    /**
+     * Generates a random union value.
+     * Selects a random branch and generates a random value for that branch, wrapping it appropriately.
+     * @returns A random union value.
+     */
+    random() {
+        const index = Math.floor(Math.random() * __classPrivateFieldGet(this, _UnionType_branches, "f").length);
+        const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[index];
+        if (branch.isNull) {
+            return null;
+        }
+        const value = branch.type.random();
+        return { [branch.name]: value };
+    }
+    /**
+     * Returns the JSON representation of the union type.
+     * An array of the JSON representations of each branch type.
+     * @returns The JSON type array.
+     */
+    toJSON() {
+        return __classPrivateFieldGet(this, _UnionType_types, "f").map((type) => type.toJSON());
+    }
+    /**
+     * Compares two serialized union values from taps for ordering.
+     * Reads the branch indices from both taps; if equal, compares the branch values using the branch type's match method.
+     * @param tap1 The first readable tap.
+     * @param tap2 The second readable tap.
+     * @returns Negative if tap1 < tap2, zero if equal, positive if tap1 > tap2.
+     */
+    async match(tap1, tap2) {
+        const idx1 = await __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_readBranchIndex).call(this, tap1);
+        const idx2 = await __classPrivateFieldGet(this, _UnionType_instances, "m", _UnionType_readBranchIndex).call(this, tap2);
+        if (idx1 === idx2) {
+            const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[idx1];
+            if (branch.isNull) {
+                return 0;
+            }
+            return await branch.type.match(tap1, tap2);
+        }
+        return idx1 < idx2 ? -1 : 1;
+    }
+    /**
+     * Creates a resolver for schema evolution from the writer type to this union type.
+     * If the writer is also a union, creates resolvers for each branch.
+     * Otherwise, finds a compatible branch in this union and creates a resolver for it.
+     * @param writerType The writer type to resolve from.
+     * @returns A resolver for the union value.
+     */
+    createResolver(writerType) {
+        if (writerType instanceof UnionType) {
+            const branchResolvers = writerType.getTypes().map((branch) => this.createResolver(branch));
+            return new UnionFromUnionResolver(this, branchResolvers);
+        }
+        for (let i = 0; i < __classPrivateFieldGet(this, _UnionType_branches, "f").length; i++) {
+            const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[i];
+            try {
+                const resolver = branch.type.createResolver(writerType);
+                return new UnionBranchResolver(this, branch, resolver);
+            }
+            catch {
+                // Continue searching for compatible branch.
+            }
+        }
+        return super.createResolver(writerType);
+    }
+}
+_UnionType_types = new WeakMap(), _UnionType_branches = new WeakMap(), _UnionType_indices = new WeakMap(), _UnionType_instances = new WeakSet(), _UnionType_resolveBranch = function _UnionType_resolveBranch(value) {
+    if (value === null) {
+        const index = __classPrivateFieldGet(this, _UnionType_indices, "f").get("null");
+        if (index === undefined) {
+            throwInvalidError([], value, this);
+        }
+        return { index, branchValue: undefined };
+    }
+    if (!isPlainObject(value)) {
+        throwInvalidError([], value, this);
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== 1) {
+        throwInvalidError([], value, this);
+    }
+    const key = keys[0];
+    const branchIndex = __classPrivateFieldGet(this, _UnionType_indices, "f").get(key);
+    if (branchIndex === undefined) {
+        throwInvalidError([], value, this);
+    }
+    const branch = __classPrivateFieldGet(this, _UnionType_branches, "f")[branchIndex];
+    const branchValue = value[key];
+    if (!branch.isNull && branchValue === undefined) {
+        throwInvalidError([], value, this);
+    }
+    if (branch.isNull && branchValue !== undefined) {
+        throwInvalidError([], value, this);
+    }
+    return { index: branchIndex, branchValue };
+}, _UnionType_readBranchIndex = async function _UnionType_readBranchIndex(tap) {
+    const indexBigInt = await tap.readLong();
+    const index = bigIntToSafeNumber(indexBigInt, "Union branch index");
+    if (index < 0 || index >= __classPrivateFieldGet(this, _UnionType_branches, "f").length) {
+        throw new Error(`Invalid union index: ${index}`);
+    }
+    return index;
+};
+class UnionBranchResolver extends Resolver {
+    constructor(reader, branch, branchResolver) {
+        super(reader);
+        _UnionBranchResolver_branch.set(this, void 0);
+        _UnionBranchResolver_branchResolver.set(this, void 0);
+        __classPrivateFieldSet(this, _UnionBranchResolver_branch, branch, "f");
+        __classPrivateFieldSet(this, _UnionBranchResolver_branchResolver, branchResolver, "f");
+    }
+    async read(tap) {
+        const resolvedValue = await __classPrivateFieldGet(this, _UnionBranchResolver_branchResolver, "f").read(tap);
+        if (__classPrivateFieldGet(this, _UnionBranchResolver_branch, "f").isNull) {
+            return null;
+        }
+        return { [__classPrivateFieldGet(this, _UnionBranchResolver_branch, "f").name]: resolvedValue };
+    }
+}
+_UnionBranchResolver_branch = new WeakMap(), _UnionBranchResolver_branchResolver = new WeakMap();
+class UnionFromUnionResolver extends Resolver {
+    constructor(reader, resolvers) {
+        super(reader);
+        _UnionFromUnionResolver_resolvers.set(this, void 0);
+        __classPrivateFieldSet(this, _UnionFromUnionResolver_resolvers, resolvers, "f");
+    }
+    async read(tap) {
+        const indexBigInt = await tap.readLong();
+        const index = bigIntToSafeNumber(indexBigInt, "Union branch index");
+        const resolver = __classPrivateFieldGet(this, _UnionFromUnionResolver_resolvers, "f")[index];
+        if (!resolver) {
+            throw new Error(`Invalid union index: ${index}`);
+        }
+        return await resolver.read(tap);
+    }
+}
+_UnionFromUnionResolver_resolvers = new WeakMap();

package/esm/schemas/error.d.ts

@@ -0,0 +1,31 @@
+import type { Type } from "./type.js";
+/**
+ * Hook function for handling validation errors.
+ */
+export type ErrorHook<T = unknown> = (path: string[], invalidValue: unknown, schemaType: Type<T>) => void;
+/**
+ * Custom error class for Avro schema validation failures.
+ */
+export declare class ValidationError<T = unknown> extends Error {
+    /** The path to the invalid value within the schema/data. */
+    readonly path: string[];
+    /** The value that failed validation. */
+    readonly value: unknown;
+    /** The schema type that rejected the value. */
+    readonly type: Type<T>;
+    /**
+     * Creates a new ValidationError.
+     * @param path The path to the invalid value.
+     * @param invalidValue The invalid value.
+     * @param schemaType The schema type.
+     */
+    constructor(path: string[], invalidValue: unknown, schemaType: Type<T>);
+}
+/**
+ * Throws a ValidationError for invalid values.
+ */
+export declare function throwInvalidError<T = unknown>(path: string[], invalidValue: unknown, schemaType: Type<T>): never;
+/**
+ * Renders a path array as a formatted tree string.
+ */
+export declare function renderPathAsTree(path: string[]): string;

package/esm/schemas/error.js

@@ -0,0 +1,67 @@
+import { safeStringify } from "./json.js";
+/**
+ * Custom error class for Avro schema validation failures.
+ */
+export class ValidationError extends Error {
+    /**
+     * Creates a new ValidationError.
+     * @param path The path to the invalid value.
+     * @param invalidValue The invalid value.
+     * @param schemaType The schema type.
+     */
+    constructor(path, invalidValue, schemaType) {
+        const serializedValue = safeStringify(invalidValue);
+        const serializedJSON = safeStringify(schemaType.toJSON());
+        let message = `Invalid value: \'${serializedValue}\' for type: ${serializedJSON}`;
+        if (path.length > 0) {
+            message += ` at path: ${renderPathAsTree(path)}`;
+        }
+        super(message);
+        /** The path to the invalid value within the schema/data. */
+        Object.defineProperty(this, "path", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The value that failed validation. */
+        Object.defineProperty(this, "value", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The schema type that rejected the value. */
+        Object.defineProperty(this, "type", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "ValidationError";
+        this.path = path;
+        this.value = invalidValue;
+        this.type = schemaType;
+    }
+}
+/**
+ * Throws a ValidationError for invalid values.
+ */
+export function throwInvalidError(path, invalidValue, schemaType) {
+    throw new ValidationError(path, invalidValue, schemaType);
+}
+/**
+ * Renders a path array as a formatted tree string.
+ */
+export function renderPathAsTree(path) {
+    if (path.length === 0)
+        return "";
+    let result = path[0];
+    for (let i = 1; i < path.length; i++) {
+        result += "\n" + "  ".repeat(i) + path[i];
+    }
+    if (path.length > 1) {
+        result = "\n" + result;
+    }
+    return result;
+}

package/esm/schemas/json.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Safely stringifies a value to JSON, handling BigInts and circular references.
+ * @param value The value to stringify.
+ * @returns The string representation.
+ */
+export declare function safeStringify(value: unknown): string;

package/esm/schemas/json.js

@@ -0,0 +1,35 @@
+/** @internal */
+export function _safeJSONStringify(obj, indent = 2) {
+    const cache = [];
+    const retVal = JSON.stringify(obj, (_key, value) => {
+        if (typeof value === "bigint")
+            return String(value);
+        if (typeof value === "object" && value !== null) {
+            if (cache.includes(value))
+                return "[Circular]";
+            cache.push(value);
+        }
+        return value;
+    }, indent);
+    cache.length = 0;
+    return retVal;
+}
+/**
+ * Safely stringifies a value to JSON, handling BigInts and circular references.
+ * @param value The value to stringify.
+ * @returns The string representation.
+ */
+export function safeStringify(value) {
+    // Converts supported primitive values and complex objects into stable JSON
+    // while handling circular references and bigint values.
+    if (typeof value === "string" || typeof value === "bigint" ||
+        typeof value === "number" || typeof value === "boolean" || value === null ||
+        typeof value === "undefined") {
+        return String(value);
+    }
+    const jsonStr = _safeJSONStringify(value);
+    if (jsonStr === undefined) {
+        return String(value);
+    }
+    return `\n${jsonStr}\n`;
+}