zod-to-x/dist/core/ast_node.d.ts

Multi language types generation from Zod schemas.

import { ASTNodes } from "../core";
import { IZod2xLayerMetadata } from "../lib/zod_ext";
import { ZodObject } from "../lib/zod_helpers";
export interface IZod2AstOpt {
    /**
     * When true, it will throw an error if a bad data modeling practice is detected.
     * Default is true.
     */
    strict?: boolean;
    /**
     * Metadata used to provide additional information to the AST nodes about layers modeling of
     * the schema.
     */
    layer?: IZod2xLayerMetadata;
    /**
     * If true, aliased basic types (string, number, boolean, etc.) from layered modeling
     * will not be extracted as named AST nodes. Instead, they will be inlined as their
     * underlying type. Useful for targets like Protobuf that don't support type aliases.
     * Default is false.
     */
    skipBasicTypes?: boolean;
}
/**
 * This class creates AST nodes used to transpile Zod Schemas to other languages.
 * Simply create an instance and call build with a ZodObject to obtain a list with transpilerable
 * nodes.
 */
export declare class Zod2Ast {
    /**
     * Transpilerable nodes of current data model
     */
    private nodes;
    /**
     * Lazy schemas for further analysis
     */
    private lazyPointers;
    /**
     * Warnings generated during the AST creation to aware user about bad practices
     */
    private warnings;
    private opt;
    constructor(opt?: IZod2AstOpt);
    /**
     * Determines if the current node is an "own property" based on the provided parent file.
     *
     * @param parentFile - The file path of the parent to compare against, if exist.
     * @returns `true` if the node is an "own property"; otherwise, `false`.
     */
    private _isOwnProperty;
    /**
     * Check if the layer of the item is compatible with the layer of the schema. If does and the
     * transpilerable item is in a different file, it returns the file name.
     *
     * @param itemName
     * @param metadata
     * @returns
     */
    private _getTranspilerableFile;
    /**
     * Transpilerable items are treated as references in the AST
     * @param node: AST node from which the definition will be created
     * @param constraints - Constraints to be added to the definition
     * @returns
     */
    private _createDefinition;
    /**
     * Extracts and formats the enumeration values from a given ZodEnum or ZodNativeEnum schema.
     * @param schema - A ZodEnum or ZodNativeEnum schema containing the enumeration values.
     * @returns A list of key-value pairs where the key is a formatted string and the value
     *          is either a string or a number.
     */
    private _getEnumValues;
    /**
     * Intersects the properties of two Zod object schemas and returns the combined properties.
     * Processes the Zod shapes directly instead of looking up cached AST nodes, ensuring that
     * instantiated generic types (from useGenericType) are correctly resolved.
     *
     * @param left - The left Zod object schema.
     * @param right - The right Zod object schema.
     * @returns An object containing the combined properties of the left and right schemas.
     */
    private _intersectAstNodes;
    /**
     * Merges multiple AST definitions into a single AST object containing combined properties.
     * - Equal properties must have the same type and array dimension.
     * - If a property is optional in one definition and required in another, it will be considered
     *      optional in the merged object.
     * - If a property is nullable in one definition and non-nullable in another, it will be
     *      considered nullable in the merged object.
     *
     * @param options - An array of AST definitions to be merged.
     * @returns An object containing the merged properties.
     * @throws AstNodeError - If properties with different types or array dimensions are encountered.
     */
    private _unionAstNodes;
    /**
     * Retrieves the name and associated transpilerable file information for a given Zod schema.
     *
     * @param schema - The Zod schema to extract the name and file information from.
     *
     * @returns An object containing the `name` of the schema and additional transpilerable file
     *          details.
     *
     * @throws AstTypeNameDefinitionError - If the schema does not have a `typeName` defined.
     * This can occur if layered modeling is used with nested schema definitions or if the `zod2x`
     * method is not used to provide a `typeName`. The error message includes details about the
     * affected type properties.
     */
    private _getNames;
    /**
     * Generates an Abstract Syntax Tree (AST) definition for a Zod enum schema.
     *
     * @param schema - The Zod enum schema to process.
     * @param opt - Optional metadata for schema processing.
     *   - `isInjectedEnum` (optional): Indicates if the enum is part of a discriminated union.
     *
     * @returns The AST definition for the provided enum schema.
     */
    private _getEnumAst;
    /**
     * Generates an abstract syntax tree (AST) definition for a Zod object schema.
     *
     * @param schema - The ZodObject schema to be converted into an AST definition.
     * @param opt - Optional metadata for schema processing.
     *   - `discriminantKey`: A key used to determine the discriminant value for the schema.
     *
     * @returns The AST definition for the provided Zod object schema.
     */
    private _getObjectAst;
    /**
     * Generates an Abstract Syntax Tree (AST) definition for a Zod union schema.
     *
     * This method processes a Zod union schema and creates an `ASTUnion` object
     * that represents the schema in an AST format. It handles both regular unions
     * and discriminated unions, and provides warnings for certain bad data modeling
     * practices, such as unions of non-object types or the use of `ZodUnion` instead
     * of `ZodDiscriminatedUnion`.
     *
     * @param schema - The Zod union schema to be converted into an AST definition.
     *                 This can be a regular union or a discriminated union.
     *
     * @returns The AST definition for the given Zod union schema.
     */
    private _getUnionAst;
    /**
     * Processes a ZodIntersection schema and generates an ASTDefinition for it.
     *
     * @param schema - The ZodIntersection schema to process, which combines two Zod types.
     *
     * @returns An ASTDefinition representing the intersection of the two Zod types.
     */
    private _getIntersectionAst;
    /**
     * Generates an AST (Abstract Syntax Tree) definition for a Zod array schema.
     *
     * @param schema - The Zod array schema to process.
     * @param innerSchema - The AST type representing the inner schema of the array.
     * @returns The AST definition for the array schema.
     */
    private _getArrayAst;
    private _getAliasAst;
    /**
     * Build the AST node of provided Zod Schema
     * @param schema
     * @returns
     */
    private _zodToAST;
    /**
     * Create the AST identifying the nodes that can be transpiled.
     * @param schema
     * @returns Transpilerable nodes.
     */
    build(schema: ZodObject<any>): ASTNodes;
}