zod-to-x 1.4.0 → 1.4.2

package/README.md

@@ -3,15 +3,14 @@
   <em style="font-size: smaller;">Image generated using Canvas AI.</em>
 </p>
 <p align="center">
-  <a href="https://github.com/rroumenov/zod-to-x/releases" target="_blank" style="text-decoration: none;">
-    <button style="padding: 6px 12px; font-size: 14px; background-color: #2ea44f; color: white; border: 1px solid rgba(27, 31, 35, 0.15); border-radius: 6px; cursor: pointer; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';">
-      View Changelog
-    </button>
+  <a href="https://github.com/rroumenov/zod-to-x/releases" target="_blank">
+    <img src="https://img.shields.io/badge/View%20Changelog-brightgreen?style=for-the-badge" alt="View Changelog">
   </a>
-  <a href="https://playcode.io/2277071" target="_blank" style="text-decoration: none; margin-left: 10px;">
-    <button style="padding: 6px 12px; font-size: 14px; background-color: #0366d6; color: white; border: 1px solid rgba(27, 31, 35, 0.15); border-radius: 6px; cursor: pointer; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';">
-      Try it on Playcode
-    </button>
+  <a href="https://playcode.io/2277071" target="_blank" style="margin-left: 10px;">
+    <img src="https://img.shields.io/badge/Try%20it%20on%20Playcode-blue?style=for-the-badge" alt="Try it on Playcode">
+  </a>
+  <a href="https://github.com/rroumenov/zod-to-x/issues" target="_blank" style="margin-left: 10px;">
+    <img src="https://img.shields.io/badge/Need%20Help%3F-orange?style=for-the-badge" alt="Need Help?">
   </a>
 </p>
 
@@ -72,7 +71,7 @@ This extension appends a `zod2x` method to:
 ## Quick start
 ```ts
 import { z } from "zod";
-import { extendZod, Zod2Ast, Zod2Ts } from "zod-to-x";
+import { extendZod, Zod2Ast, Zod2XTranspilers } from "zod-to-x";
 extendZod(z); // The extend step can be skipped if it has already been done.
 
 /**
@@ -95,7 +94,7 @@ const visitorNodes = new Zod2Ast().build(VisitorSchema);
  * 3) Generate types in the desired language.
  *    Depending on the transpiled language, data models can be generated using classes.
  */
-const tsVisitorAsInterface: string = new Zod2Ts().transpile(visitorNodes);
+const tsVisitorAsInterface: string = new Zod2XTranspilers.Zod2Ts().transpile(visitorNodes);
 console.log(tsVisitorAsInterface)
 // output:
 // export interface Visitor {
@@ -106,7 +105,7 @@ console.log(tsVisitorAsInterface)
 //     comments?: string;
 // }
 
-const tsVisitorAsClass: string = new Zod2Ts({outType: "class"}).transpile(visitorNodes);
+const tsVisitorAsClass: string = new Zod2XTranspilers.Zod2Ts({outType: "class"}).transpile(visitorNodes);
 console.log(tsVisitorAsClass)
 // output:
 // export class Visitor {
@@ -256,9 +255,13 @@ inline void from_json(const json& j, Message& x) {
 ## Layered modeling
 To improve Separation of Concerns (SoC), the Dependency Rule, and Maintainability, a new layer-based modeling approach was introduced in `v1.4.0`. This approach establishes relationships between models in separate files, which are transpiled into file imports. This feature provides a powerful tool not only for type systems with robust architectures, such as Clean, Hexagonal, or Layered, but also enforces their usage.
 
-To achieve this, two new components are included:
+To achieve this, new components are included:
 - **Zod2XModel**: With layered modeling, data is defined using classes. Inheriting this abstract class provides metadata management to handle relationships and also simplifies transpilation by including a `transpile()` method that receives the target language class.
-- **Layer**: A class decorator that defines class metadata, including a reference to the output file of the modeled data, a namespace under which its types are grouped, and an integer index representing the layer number. It can also be used as a decorator factory to define custom layers. Out of the box, four layers are provided: *Domain*, *Application*, *Infrastructure*, and *Presentation*.
+- **Layer**: A class decorator that defines class metadata, including a reference to the output file of the modeled data, a namespace under which its types are grouped, and an integer index representing the layer number. It can also be used as a decorator factory to define custom layers. Out of the box, four layers are provided: *Domain*, *Application*, *Infrastructure*, and *Presentation*. Parameters:  
+  - **namespace**: Defines the namespace under which the types are grouped.
+  - **file**: Specifies the expected output file where the transpiled types will be saved.
+  - **externalInheritance**: When a type from one layer is imported into another layer without modifications, it is transpiled as a new type inheriting from the imported type. This ensures type consistency across layers while maintaining reusability. See example (4) below. The default value is `true`.
+- **Zod2XMixin**: A function that enables the creation of layers by extending multiple data models, thereby simplifying their definition and organization.
 
 ### Usage example
 1. Define a Domain model, such as a User entity:
@@ -319,7 +322,7 @@ class UserDtos extends Zod2XModel {
 }
 
 const userDtos = new UserDtos();
-console.log(userDtos.transpile(Transpilers.Zod2Ts))
+console.log(userDtos.transpile(Zod2XTranspilers.Zod2Ts))
 // Output:
 // import * as USER from "./user.entity";    <--- Reusing models from other layers.
 
@@ -347,13 +350,128 @@ console.log(userDtos.transpile(Transpilers.Zod2Ts))
 ```
 **(*)** Any modification of an existing model (in this case, `userEntity`) will lose the relation with that model, but not its children. In the case of the `CreateUserUseCaseDto` type, the `role` field will remain linked to the existing one in the `user.entity` file.
 
+3 - Are your models too large? Simplify them!  
+If you are dealing with complex models whose definitions are too extensive, split them into multiple classes and then combine them using `Zod2XMixin` as shown below:
+```ts
+// Sub-models do not require a layer decorator; it is applied automatically when inherited by the main model.
+
+// Sub-model 1
+class CreateUserUseCaseDto {
+    createUserUseCaseDto = userModels.userEntity.omit({ id: true });
+}
+
+// Sub-model 2
+class CreateUserUseCaseResultDto {
+    createUserUseCaseResultDto = userModels.userEntity
+        .omit({ role: true })
+        .extend({
+            createdAt: z.date(),
+            updatedAt: z.date(),
+        });
+}
+
+// Main model
+@Application({ namespace: "USER_DTOS", file: "user.dtos" })
+class UserDtos extends Zod2XMixin(
+    [CreateUserUseCaseDto, CreateUserUseCaseResultDto], // Inherit the desired sub-models.
+    Zod2XModel  // Zod2XModel must still be the base class.
+) {}
+
+export const userDtos = new UserDtos();
+console.log(userDtos.transpile(Zod2XTranspilers.Zod2Ts))
+// Output (same as above):
+// import * as USER from "./user.entity";    <--- Reusing models from other layers.
+
+// export interface CreateUserUseCaseDto {
+//     name: string;
+//     email: string;
+//     age?: number;
+//     role: USER.UserRole;
+// }
+
+// export interface CreateUserUseCaseResultDto {
+//     id: string;
+//     name: string;
+//     email: string;
+//     age?: number;
+//     createdAt: Date;
+//     updatedAt: Date;
+// }
+
+// export interface UserDtos {
+//     createUserUseCaseDto: CreateUserUseCaseDto;
+//     createUserUseCaseResultDto: CreateUserUseCaseResultDto;
+// }
+```
+
+4 - Difference of using **externalInheritance** (defaults) or not.  
+```ts
+// Default output (externalInheritance = true)
+@Application({ namespace: "USER_DTOS", file: "user.dtos" })
+class UserDtos extends Zod2XModel {
+
+    createUserUseCaseDto = userModels.userEntity.omit({ id: true });
+
+    createUserUseCaseResultDto = userModels.userEntity;
+}
+
+// Output:
+// import * as USER from "./user.entity";
+
+// export interface CreateUserUseCaseDto {
+//     name: string;
+//     email: string;
+//     age?: number;
+//     role: USER.UserRole;
+// }
+
+// export interface CreateUserUseCaseResultDto extends USER.UserEntity {}
+
+// export interface UserDtos {
+//     createUserUseCaseDto: CreateUserUseCaseDto;
+//     createUserUseCaseResultDto: CreateUserUseCaseResultDto;
+// }
+
+// ---------------
+// If `USER.UserEntity` were a Union or a Discriminated Union, the output would be a Type equivalent to `USER.UserEntity` rather than an Interface that extends it.  
+
+```
+
+```ts
+// Output without externalInheritance
+@Application({ namespace: "USER_DTOS", file: "user.dtos",  externalInheritance: false})
+class UserDtos extends Zod2XModel {
+
+    createUserUseCaseDto = userModels.userEntity.omit({ id: true });
+
+    createUserUseCaseResultDto = userModels.userEntity;
+}
+
+// Output:
+// import * as USER from "./user.entity";
+
+// export interface CreateUserUseCaseDto {
+//     name: string;
+//     email: string;
+//     age?: number;
+//     role: USER.UserRole;
+// }
+
+// export interface UserDtos {
+//     createUserUseCaseDto: CreateUserUseCaseDto;
+//     createUserUseCaseResultDto: USER.UserEntity;
+// }
+
+// ---------------
+// In this case, the type of `createUserUseCaseResultDto` is inferred from the parent model (`UserDtos`), but there is no explicit definition of the type itself.
+```
+
 
 ## Supported output languages
 Common options:
 - **header**: Text to add as a comment at the beginning of the output.
 - **indent**: Number of spaces to use for indentation in the generated code. Defaults to 4 if not specified.
 - **includeComments**: Determines whether to include comments in the transpiled code. Defaults to `true`.
-- **skipDiscriminatorNodes**: prevents the inclusion of `ZodEnum` or `ZodNativeEnum` schemas that are used solely as discriminator keys in a `ZodDiscriminatedUnion`. Defaults to `false`.
 
 ### 0) ASTNode
 - Options:

package/dist/core/ast_node.d.ts

@@ -23,14 +23,6 @@ export declare class Zod2Ast {
      * Transpilerable nodes of current data model
      */
     private nodes;
-    /**
-     * Transpilerable nodes of external data models (used for layered modeling)
-     */
-    private externalNodes;
-    /**
-     * Additional transpilerable nodes supplied by ZodDiscriminatedUnion
-     */
-    private discriminatorNodes;
     /**
      * Lazy schemas for further analysis
      */
@@ -87,7 +79,6 @@ export declare class Zod2Ast {
      */
     private _unionAstNodes;
     private _getNames;
-    private _getNode;
     private _getEnumAst;
     private _getObjectAst;
     private _getUnionAst;

package/dist/core/ast_node.js

@@ -13,8 +13,6 @@ class Zod2Ast {
     constructor(opt = {}) {
         var _a;
         this.nodes = new Map();
-        this.externalNodes = new Map();
-        this.discriminatorNodes = new Map();
         this.lazyPointers = [];
         this.warnings = [];
         this.opt = Object.assign(Object.assign({}, opt), { strict: (_a = opt.strict) !== null && _a !== void 0 ? _a : true });
@@ -27,14 +25,20 @@ class Zod2Ast {
      * @param layerMetadata
      * @returns
      */
-    _getTranspilerableFile(itemName, layerMetadata) {
-        if (this.opt.layer && layerMetadata) {
-            if (this.opt.layer.index < layerMetadata.index) {
+    _getTranspilerableFile(itemName, metadata) {
+        var _a;
+        const layer = (_a = metadata === null || metadata === void 0 ? void 0 : metadata.parentLayer) !== null && _a !== void 0 ? _a : metadata === null || metadata === void 0 ? void 0 : metadata.layer;
+        if (this.opt.layer && layer) {
+            if (this.opt.layer.index < layer.index) {
                 throw new errors_1.BadLayerDefinitionError(`${itemName}: Layer with number ${this.opt.layer.index} can only use models` +
-                    `from the same or lower layer. Found layer with number ${layerMetadata.index}`);
+                    `from the same or lower layer. Found layer with number ${layer.index}`);
             }
-            if (this.opt.layer.file !== layerMetadata.file) {
-                return { parentFile: layerMetadata.file, parentNamespace: layerMetadata.namespace };
+            if (this.opt.layer.file !== layer.file) {
+                return {
+                    parentFile: layer.file,
+                    parentNamespace: layer.namespace,
+                    parentTypeName: metadata === null || metadata === void 0 ? void 0 : metadata.parentTypeName,
+                };
             }
         }
         return {};
@@ -144,63 +148,51 @@ class Zod2Ast {
         };
     }
     _getNames(schema, errorString) {
-        var _a, _b;
+        var _a;
         const name = (_a = schema._zod2x) === null || _a === void 0 ? void 0 : _a.typeName;
         if (!name) {
             throw new errors_1.AstTypeNameDefinitionError(errorString);
         }
-        return Object.assign({ name, typeName: schema._def.typeName }, this._getTranspilerableFile(name, (_b = schema._zod2x) === null || _b === void 0 ? void 0 : _b.layer));
-    }
-    _getNode(fileName) {
-        return fileName ? this.externalNodes : this.nodes;
+        return Object.assign({ name, zodTypeName: schema._def.typeName }, this._getTranspilerableFile(name, schema._zod2x));
     }
     _getEnumAst(schema, opt) {
-        const { name, typeName, parentFile, parentNamespace } = this._getNames(schema, "ZodEnum/ZodNativeEnum type must have a typeName. Use zod2x method to provide one.");
+        const { name, zodTypeName, parentFile, parentNamespace, parentTypeName } = this._getNames(schema, "ZodEnum/ZodNativeEnum type must have a typeName. Use zod2x method to provide one.");
         const item = {
-            type: typeName,
+            type: zodTypeName,
             name,
             values: this._getEnumValues(schema),
             description: schema._def.description,
             parentFile,
             parentNamespace,
+            parentTypeName,
+            isFromDiscriminatedUnion: opt === null || opt === void 0 ? void 0 : opt.isInjectedEnum,
         };
-        const node = this._getNode(parentFile);
-        if (opt === null || opt === void 0 ? void 0 : opt.isInjectedEnum) {
-            if (!node.has(name) && !this.discriminatorNodes.has(name)) {
-                this.discriminatorNodes.set(name, item);
-            }
-        }
-        else {
-            if (!node.has(name)) {
-                node.set(name, item);
-            }
-            if (this.discriminatorNodes.has(name)) {
-                this.discriminatorNodes.delete(name);
-            }
+        if (!this.nodes.has(name)) {
+            this.nodes.set(name, item);
         }
-        return this._createDefinition(name, typeName, undefined, parentNamespace);
+        return this._createDefinition(name, zodTypeName, undefined, parentNamespace);
     }
     _getObjectAst(schema, opt) {
-        const { name, typeName, parentFile, parentNamespace } = this._getNames(schema, "ZodObject type must have a typeName. Use zod2x method to provide one.");
+        const { name, zodTypeName, parentFile, parentNamespace, parentTypeName } = this._getNames(schema, "ZodObject type must have a typeName. Use zod2x method to provide one.");
         let discriminantValue = undefined;
         const shape = schema._def.shape();
-        const node = this._getNode(parentFile);
-        if (!node.has(name)) {
+        if (!this.nodes.has(name)) {
             const properties = {};
             for (const key in shape) {
                 properties[key] = this._zodToAST(shape[key]);
             }
-            node.set(name, {
+            this.nodes.set(name, {
                 type: zod_1.ZodFirstPartyTypeKind.ZodObject,
                 name,
                 properties,
                 description: schema.description,
                 parentFile,
                 parentNamespace,
+                parentTypeName,
             });
         }
         if (opt === null || opt === void 0 ? void 0 : opt.discriminantKey) {
-            const item = node.get(name);
+            const item = this.nodes.get(name);
             if (Object.keys(item.properties).includes(opt.discriminantKey)) {
                 const key = opt.discriminantKey;
                 if (item.properties[key].type === zod_1.ZodFirstPartyTypeKind.ZodLiteral) {
@@ -213,22 +205,22 @@ class Zod2Ast {
                 }
             }
         }
-        return this._createDefinition(name, typeName, discriminantValue, parentNamespace);
+        return this._createDefinition(name, zodTypeName, discriminantValue, parentTypeName ? undefined : parentNamespace);
     }
     _getUnionAst(schema) {
         const def = schema._def;
         const discriminator = schema instanceof zod_1.ZodDiscriminatedUnion ? schema._def.discriminator : undefined;
-        const { name, typeName, parentFile, parentNamespace } = this._getNames(schema, "ZodUnion/ZodDiscriminatedUnion type must have a typeName. " +
+        const { name, zodTypeName, parentFile, parentNamespace, parentTypeName } = this._getNames(schema, "ZodUnion/ZodDiscriminatedUnion type must have a typeName. " +
             "Use zod2x method to provide one.");
-        const node = this._getNode(parentFile);
         const item = {
-            type: typeName,
+            type: zodTypeName,
             name,
             options: def.options.map((i) => this._zodToAST(i, { discriminantKey: discriminator })),
             description: schema.description,
             discriminantKey: discriminator,
             parentFile,
             parentNamespace,
+            parentTypeName,
         };
         if (!def.options.every((i) => i instanceof zod_1.ZodObject)) {
             this.warnings.push("Union of non-object types is a bad data modeling practice, " +
@@ -246,15 +238,14 @@ class Zod2Ast {
                     `${item.options.map((i) => i.reference).join(", ")}`,
             };
         }
-        if (name && !node.has(name)) {
-            node.set(name, item);
+        if (name && !this.nodes.has(name)) {
+            this.nodes.set(name, item);
         }
-        return this._createDefinition(name, typeName, undefined, parentNamespace);
+        return this._createDefinition(name, zodTypeName, undefined, parentTypeName ? undefined : parentNamespace);
     }
     _getIntersectionAst(schema) {
         const def = schema._def;
-        const { name, typeName, parentFile, parentNamespace } = this._getNames(schema, "ZodIntersection type must have a typeName. Use zod2x method to provide one.");
-        const node = this._getNode(parentFile);
+        const { name, zodTypeName, parentFile, parentNamespace, parentTypeName } = this._getNames(schema, "ZodIntersection type must have a typeName. Use zod2x method to provide one.");
         const item = {
             type: zod_1.ZodFirstPartyTypeKind.ZodIntersection,
             name,
@@ -263,6 +254,7 @@ class Zod2Ast {
             description: schema.description,
             parentFile,
             parentNamespace,
+            parentTypeName,
         };
         if (def.left._def.typeName !== "ZodObject" || def.right._def.typeName !== "ZodObject") {
             this.warnings.push("Intersection of non-object is a bad data modeling practice, " +
@@ -279,10 +271,10 @@ class Zod2Ast {
                     `${item.right.reference}`,
             };
         }
-        if (name && !node.has(name)) {
-            node.set(name, item);
+        if (name && !this.nodes.has(name)) {
+            this.nodes.set(name, item);
         }
-        return this._createDefinition(name, typeName, undefined, parentNamespace);
+        return this._createDefinition(name, zodTypeName, undefined, parentTypeName ? undefined : parentNamespace);
     }
     /**
      * Build the AST node of provided Zod Schema
@@ -450,8 +442,6 @@ class Zod2Ast {
         }
         return {
             nodes: this.nodes,
-            externalNodes: this.externalNodes,
-            discriminatorNodes: this.discriminatorNodes,
             warnings: this.warnings,
         };
     }

package/dist/core/ast_types.d.ts

@@ -8,6 +8,19 @@ export type ASTCommon = {
     isNullable?: boolean;
     isOptional?: boolean;
 };
+export type ASTLayerMetadata = {
+    /**
+     * File where the transpilerable model is defined and the reference used to group imports.
+     * Used to generate import statements in the transpiled code.
+     */
+    parentFile?: string;
+    parentNamespace?: string;
+    /**
+     * For Layered Modeling.
+     * Stores the used type from an external model. Used to create models inheritance.
+     */
+    parentTypeName?: string;
+};
 /**
  * AST (Abstract Syntax Tree) type for each Zod Schema that encapsulates
  * additional information beyond just the schema type.
@@ -48,17 +61,25 @@ export type ASTEnum = {
     type: ZodFirstPartyTypeKind.ZodEnum;
     name: string;
     values: [string, string | number][];
-};
+    /**
+     * The enum is injected using zod2x method during ZodDiscriminatedUnion creation.
+     */
+    isFromDiscriminatedUnion?: boolean;
+} & ASTLayerMetadata;
 export type ASTNativeEnum = {
     type: ZodFirstPartyTypeKind.ZodNativeEnum;
     name: string;
     values: [string, string | number][];
-};
+    /**
+     * The enum is injected using zod2x method during ZodDiscriminatedUnion creation.
+     */
+    isFromDiscriminatedUnion?: boolean;
+} & ASTLayerMetadata;
 export type ASTObject = {
     type: ZodFirstPartyTypeKind.ZodObject;
     name: string;
     properties: Record<string, ASTNode>;
-};
+} & ASTLayerMetadata;
 export type ASTUnion = {
     type: ZodFirstPartyTypeKind.ZodUnion;
     name: string;
@@ -68,13 +89,13 @@ export type ASTUnion = {
      * have a variant type or discriminated union cannot be used.
      */
     newObject?: ASTCommon & ASTObject;
-};
+} & ASTLayerMetadata;
 export type ASTDiscriminatedUnion = {
     type: ZodFirstPartyTypeKind.ZodDiscriminatedUnion;
     name: string;
     options: ASTNode[];
     discriminantKey?: string;
-};
+} & ASTLayerMetadata;
 export type ASTIntersection = {
     type: ZodFirstPartyTypeKind.ZodIntersection;
     name: string;
@@ -85,7 +106,7 @@ export type ASTIntersection = {
      * support multiple inheritance.
      */
     newObject?: ASTCommon & ASTObject;
-};
+} & ASTLayerMetadata;
 /**
  * Represents a type definition in the AST. Used to reduce node size and identify
  * schemas that can be referenced in a transpilation process.
@@ -119,17 +140,8 @@ export type ASTNode = ASTCommon & ({
 /**
  * Represents schemas that can be directly transpiled into types in other programming languages.
  */
-export type TranspilerableTypes = ASTCommon & (ASTEnum | ASTNativeEnum | ASTObject | ASTUnion | ASTDiscriminatedUnion | ASTIntersection) & {
-    /**
-     * File where the transpilerable model is defined and the reference used to group imports.
-     * Used to generate import statements in the transpiled code.
-     */
-    parentFile?: string;
-    parentNamespace?: string;
-};
+export type TranspilerableTypes = ASTCommon & (ASTEnum | ASTNativeEnum | ASTObject | ASTUnion | ASTDiscriminatedUnion | ASTIntersection);
 export type ASTNodes = {
     nodes: Map<string, TranspilerableTypes>;
-    externalNodes: Map<string, TranspilerableTypes>;
-    discriminatorNodes: Map<string, TranspilerableTypes>;
     warnings: string[];
 };

package/dist/core/transpiler.d.ts

@@ -19,13 +19,6 @@ export interface IZodToXOpt extends Record<string, any> {
      * Defaults to `true`.
      */
     includeComments?: boolean;
-    /**
-     * When set to `true`, this option excludes discriminator enums from the output types.
-     * Specifically, it prevents the inclusion of `ZodEnum` or `ZodNativeEnum` schemas that are used
-     * solely as discriminator keys in a `ZodDiscriminatedUnion`. This helps avoid adding
-     * enum types to the generated output when unnecessary.
-     */
-    skipDiscriminatorNodes?: boolean;
     /**
      * Every external type will be imported from the file where it is defined. Default: true
      */
@@ -39,7 +32,9 @@ export interface IZodToXOpt extends Record<string, any> {
 export declare abstract class Zod2X<T extends IZodToXOpt> {
     protected output: string[];
     protected indent: TIndentationLevels;
+    protected preImports: Set<string>;
     protected imports: Set<string>;
+    protected postImports: Set<string>;
     protected opt: Partial<T>;
     protected constructor(opt: Partial<T>);
     /**
@@ -60,6 +55,15 @@ export declare abstract class Zod2X<T extends IZodToXOpt> {
      * @param typeName
      */
     protected abstract getTypeFromExternalNamespace(namespace: string, typeName: string): string;
+    /**
+     * For Layered Modeling.
+     * If a property type is an imported type, without any modification, the transpiled type will be
+     * an inherited type from the imported type.
+     * @param name
+     * @param parentNamespace
+     * @param parentTypeName
+     */
+    protected abstract addExtendedType(name: string, parentNamespace: string, parentTypeName: string): void;
     /**
      * Returns a comment.
      */
@@ -183,13 +187,30 @@ export declare abstract class Zod2X<T extends IZodToXOpt> {
      * @returns A string representing the type in the target language.
      */
     protected getAttributeType(token: ASTNode | TranspilerableTypes): string;
+    /**
+     * Adds an external type import to the transpiler's imports if the provided transpiled item
+     * is located into another file and namespace, and if the `useImports` option is not disabled.
+     *
+     * @param item - An object of type `TranspilerableTypes` containing information
+     *                  about the type to be imported, including its parent file and namespace.
+     * @returns `true` if the import was successfully added, otherwise `false`.
+     */
+    protected addExternalTypeImport(item: TranspilerableTypes): boolean;
     /**
      * Transpiles a single item from the transpiler queue.
      * @param item - The transpilerable type to transpile.
      */
     private _transpileItem;
-    private _getTranspilerableNodes;
-    private _getImports;
+    /**
+     * Constructs and returns an array of strings representing the header section
+     * of the transpiled output. The header may include custom comments, pre-imports,
+     * imports, and post-imports, depending on the provided options and internal state.
+     *
+     * Each section is separated by an empty string for readability.
+     *
+     * @returns An array of strings representing the header section.
+     *
+     */
     private _getHeader;
     /**
      * Transpiles a queue of AST nodes into the target language.