zod-to-x 1.4.6-dev.2 → 1.4.6

package/README.md

@@ -25,10 +25,19 @@
 - [Installation](#installation)
 - [Quick start](#quick-start)
 - [Intersections and Unions](#intersections-and-unions)
+  - [Expected outputs](#expected-outputs)
+  - [Tips for discriminated unions](#tips-for-discriminated-unions)
 - [Layered modeling](#layered-modeling) <sup>*(new)*</sup>
-- [Supported output languages](#supported-output-languages)
+  - [Usage example](#usage-example)
+  - [Custom layers](#custom-layers)
+- [Currently supported output languages](#currently-supported-output-languages)
+  - [Typescript](#1-typescript)
+  - [C++](#2-c)
 - [Additional utils](#additional-utils)
+  - [JSON Schema definitions](#1-zod2jsonschemadefinitions)
+  - [Protobuf V3 generation](#2-zod2protov3)
 - [Mapping of supported Zod Types by Language](#mapping-of-supported-zod-types-by-langauge)
+- [Considerations](#considerations)
 
 
 
@@ -251,9 +260,11 @@ To improve Separation of Concerns (SoC), the Dependency Rule, and Maintainabilit
 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*. Parameters:  
+  - **index**: Defines the layer boundary. In layer terms, a greater number represents a more external layer. Outer layers can use models from equal or lower layers, but not from higher layers. Otherwise, an error will be raised.
   - **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`.
+  - **basicTypes**: Since `v1.4.6`, primitive data types and arrays are also transpiled when using Layered modeling **if they are declared as property inside the layer class**. They are output as aliases of the types they represent. Setting it to `false` will disable this behavior (except for arrays, which are always transpiled). Default is `true`.
 - **Zod2XMixin**: A function that enables the creation of layers by extending multiple data models, thereby simplifying their definition and organization.
 
 ### Usage example
@@ -264,10 +275,12 @@ class UserModels extends Zod2XModel {
 
     userRole = z.enum(["Admin", "User"]).zod2x("UserRole"); // (*)
 
+    userEmail = z.string().email(); // This will be transpiled as an alias.
+
     userEntity = z.object({
         id: z.string().uuid(),
         name: z.string().min(1),
-        email: z.string().email(),
+        email: this.userEmail,
         age: z.number().int().nonnegative().optional(),
         role: this.userRole,
     }); // (*)
@@ -281,10 +294,12 @@ console.log(userModels.transpile(Zod2XTranspilers.Zod2Ts));
 //     User = "User",
 // }
 
+// export type UserEmail = string;
+
 // export interface UserEntity {
 //     id: string;
 //     name: string;
-//     email: string;
+//     email: UserEmail;
 //     age?: number;
 //     role: UserRole;
 // }
@@ -321,7 +336,7 @@ console.log(userDtos.transpile(Zod2XTranspilers.Zod2Ts))
 
 // export interface CreateUserUseCaseDto {
 //     name: string;
-//     email: string;
+//     email: USER.UserEmail;
 //     age?: number;
 //     role: USER.UserRole;
 // }
@@ -329,7 +344,7 @@ console.log(userDtos.transpile(Zod2XTranspilers.Zod2Ts))
 // export interface CreateUserUseCaseResultDto {
 //     id: string;
 //     name: string;
-//     email: string;
+//     email: USER.UserEmail;
 //     age?: number;
 //     createdAt: Date;
 //     updatedAt: Date;
@@ -461,8 +476,33 @@ class UserDtos extends Zod2XModel {
 // In this case, the type of `createUserUseCaseResultDto` is inferred from the parent model (`UserDtos`), but there is no explicit definition of the type itself.
 ```
 
+### Custom Layers
+If the provided layer decorators do not meet your requirements, you can easily define custom ones:
+```ts
+import { Layer, IZod2xLayerMetadata, Zod2XModel } from "zod-to-x";
+
+// Create an enumerate with layer indexes
+enum MyLayers {
+    MyDomainLayer = 0,
+    MyApplicationLayer = 1,
+    MyInfrastructureLayer = 2,
+    // ...
+}
+
+// Create custom layer decorators
+function MyDomainLayer(opt: Omit<IZod2xLayerMetadata, "index">) {
+  return Layer({ ...opt, index: MyLayers.MyDomainLayer });
+}
+// ...
 
-## Supported output languages
+// Use the custom decorators
+@MyDomainLayer({file: "...", namespace: "..."})
+class MyEntityModels extends Zod2XModel {
+  // ...
+}
+```
+
+## Currently 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.
@@ -552,4 +592,60 @@ console.log(createUserDtoProtobuf); // Proto file of CreateUserUseCaseDto's mode
 
 
 ## Mapping of supported Zod Types by Langauge
-For a detailed mapping of supported Zod types across supported targets, please refer to the [SUPPORTED_ZOD_TYPES.md](https://github.com/rroumenov/zod-to-x/blob/main/SUPPORTED_ZOD_TYPES.md) file.
+For a detailed mapping of supported Zod types across supported targets, please refer to the [SUPPORTED_ZOD_TYPES.md](https://github.com/rroumenov/zod-to-x/blob/main/SUPPORTED_ZOD_TYPES.md) file.
+
+
+
+## Considerations
+- Choose the approach that best suits your needs, either Layered or non-Layered modeling, and avoid mixing them whenever possible, especially when working with enumerations, objects, unions, or intersections (except for `ZodLiteral.zod2x()`, which simply links a literal value to the enumeration it belongs to, if applicable). Their metadata handling differs slightly, which may result in some types not being transpiled as expected.
+
+- In Layered modeling, the transpilation of primitive types can be completely disabled or combined by defining them outside the layer class:
+```ts
+// External primitive
+const stringUUID = z.string().uuid();
+
+@Domain({ namespace: "USER", file: "user.entity" })
+class UserModels extends Zod2XModel {
+
+    // Internal primitive
+    userEmail = z.string().email(); // This will be transpiled as an alias. It is a layer property.
+
+    userEntity = z.object({
+        id: stringUUID, // "stringUUID" will not be transpiled as an alias. It is not a layer property.
+        email: this.userEmail,
+    });
+}
+
+export const userModels = new UserModels();
+```
+
+- Avoid internal alias redeclarations. If really needed, `ZodLazy` shall be used:
+```ts
+// Consider the previous UserModels
+
+import { z } from "zod";
+
+@Application({ namespace: "USER_DTOS", file: "user.dtos",  externalInheritance: false})
+class UserDtos extends Zod2XModel {
+
+    // OK - Type declaration. It creates a new type based on userEntity but without ID.
+    createUserUseCaseDto = userModels.userEntity.omit({ id: true });
+
+    // OK - Redeclaration of external type. Could be useful for typing coherence.
+    // "createUserUseCaseResultDto" becomes an alias of "userModels.userEntity".
+    createUserUseCaseResultDto = userModels.userEntity;
+
+    // OK - Redeclaration of an internal type. Could be useful for typing coherence.
+    // "createUserUseCaseDtoV2" becomes an alias of "createUserUseCaseDto".
+    createUserUseCaseDtoV2 = this.createUserUseCaseDto;
+
+    // NOK - Redeclaration of an alias. It will be an alias of "userModels.userEntity"
+    // because "createUserUseCaseResultDto" is aliased during runtime.
+    createUserUseCaseResultDtoV2 = this.createUserUseCaseResultDto;
+
+    // OK, but avoid it - Redeclaration of an alias. It will wait until
+    // "createUserUseCaseResultDto" is aliased and then will becosa an alias
+    // of "createUserUseCaseResultDto"
+    createUserUseCaseResultDtoV3 = z.lazy(() => this.createUserUseCaseResultDto),
+}
+```

package/dist/core/ast_node.d.ts

@@ -149,6 +149,7 @@ export declare class Zod2Ast {
      * @returns The AST definition for the array schema.
      */
     private _getArrayAst;
+    private _getAliasAst;
     /**
      * Build the AST node of provided Zod Schema
      * @param schema

package/dist/core/ast_node.js

@@ -410,6 +410,21 @@ class Zod2Ast {
         }
         return this._createDefinition(item);
     }
+    _getAliasAst(schema, item) {
+        var _a;
+        if (((_a = schema._zod2x) === null || _a === void 0 ? void 0 : _a.typeName) === undefined) {
+            return item;
+        }
+        const { name, parentFile, parentNamespace, aliasOf } = this._getNames(schema);
+        item.name = name;
+        item.parentFile = parentFile;
+        item.parentNamespace = parentNamespace;
+        item.aliasOf = aliasOf;
+        if (!this.nodes.has(name)) {
+            this.nodes.set(name, item);
+        }
+        return this._createDefinition(item);
+    }
     /**
      * Build the AST node of provided Zod Schema
      * @param schema
@@ -419,22 +434,22 @@ class Zod2Ast {
         var _a, _b, _c, _d, _e;
         const def = schema._def;
         if (zod_helpers_1.ZodHelpers.isZodString(schema)) {
-            return new core_1.ASTString({ description: schema.description });
+            return this._getAliasAst(schema, new core_1.ASTString({ description: schema.description }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodAnyNumberType(schema)) {
-            return new core_1.ASTNumber({
+            return this._getAliasAst(schema, new core_1.ASTNumber({
                 description: schema.description,
                 constraints: zod_helpers_1.ZodHelpers.getZodNumberConstraints(schema),
-            });
+            }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodBoolean(schema)) {
-            return new core_1.ASTBoolean({ description: schema.description });
+            return this._getAliasAst(schema, new core_1.ASTBoolean({ description: schema.description }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodDate(schema)) {
-            return new core_1.ASTDate({ description: schema.description });
+            return this._getAliasAst(schema, new core_1.ASTDate({ description: schema.description }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodAny(schema)) {
-            return new core_1.ASTAny({ description: schema.description });
+            return this._getAliasAst(schema, new core_1.ASTAny({ description: schema.description }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodNullable(schema)) {
             const subSchema = this._zodToAST(schema.unwrap());
@@ -468,10 +483,10 @@ class Zod2Ast {
             }
         }
         else if (zod_helpers_1.ZodHelpers.isZodSet(schema)) {
-            return new core_1.ASTSet({
+            return this._getAliasAst(schema, new core_1.ASTSet({
                 value: this._zodToAST(def.valueType),
                 description: schema.description,
-            });
+            }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodLiteral(schema)) {
             let parentEnum = undefined;
@@ -490,12 +505,12 @@ class Zod2Ast {
             });
         }
         else if (zod_helpers_1.ZodHelpers.isZodAnyMapType(schema)) {
-            return new core_1.ASTMap({
+            return this._getAliasAst(schema, new core_1.ASTMap({
                 type: zod_helpers_1.ZodHelpers.isZodRecord(schema) ? "record" : "map",
                 key: this._zodToAST(def.keyType),
                 value: this._zodToAST(def.valueType),
                 description: schema.description,
-            });
+            }));
         }
         else if (zod_helpers_1.ZodHelpers.isZodLazy(schema)) {
             /** Lazy items use to be recursive schemas of its own, so the are trated as another
@@ -506,10 +521,10 @@ class Zod2Ast {
             return lazyPointer;
         }
         else if (zod_helpers_1.ZodHelpers.isZodTuple(schema)) {
-            return new core_1.ASTTuple({
+            return this._getAliasAst(schema, new core_1.ASTTuple({
                 items: def.items.map(this._zodToAST.bind(this)),
                 description: schema.description,
-            });
+            }));
             /**
              *
              *

package/dist/core/transpiler.d.ts

@@ -176,6 +176,12 @@ export declare abstract class Zod2X<T extends IZodToXOpt> {
      * @returns `true` if the type is transpilerable; otherwise, `false`.
      */
     protected isTranspilerable(token: ASTNode): boolean;
+    /**
+     * Determines if the given AST node represents an aliased type.     *
+     * @param token - The AST node to evaluate.
+     * @returns `true` if the token is an instance of an aliased type, otherwise `false`.
+     */
+    protected isAliasedType(token: ASTNode): boolean;
     protected push0: (data: string) => number;
     protected push1: (data: string) => number;
     protected push2: (data: string) => number;

package/dist/core/transpiler.js

@@ -36,6 +36,23 @@ class Zod2X {
             token instanceof core_1.ASTUnion ||
             token instanceof core_1.ASTIntersection);
     }
+    /**
+     * Determines if the given AST node represents an aliased type.     *
+     * @param token - The AST node to evaluate.
+     * @returns `true` if the token is an instance of an aliased type, otherwise `false`.
+     */
+    isAliasedType(token) {
+        return (token instanceof core_1.ASTString ||
+            token instanceof core_1.ASTNumber ||
+            token instanceof core_1.ASTBoolean ||
+            token instanceof core_1.ASTLiteral ||
+            token instanceof core_1.ASTDate ||
+            token instanceof core_1.ASTAny ||
+            token instanceof core_1.ASTMap ||
+            token instanceof core_1.ASTSet ||
+            token instanceof core_1.ASTTuple ||
+            token instanceof core_1.ASTArray);
+    }
     /**
      * Adds a comment to the transpiled output.
      * @param data - The comment text to add.
@@ -163,7 +180,7 @@ class Zod2X {
         else if (item instanceof core_1.ASTIntersection) {
             this.transpileIntersection(item);
         }
-        else if (item instanceof core_1.ASTArray) {
+        else if (this.isAliasedType(item)) {
             this.transpileAliasedType(item);
         }
         else if (item instanceof core_1.ASTCommon) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { extendZod } from "./lib/zod_ext";
+export { extendZod, IZod2xLayerMetadata } from "./lib/zod_ext";
 export * as Zod2XTypes from "./core/ast-types";
 export { Zod2Ast } from "./core/ast_node";
 export { Zod2X } from "./core/transpiler";

package/dist/layered-modeling/layer.js

@@ -104,7 +104,8 @@ function Layer(opt) {
                     };
                     Object.getOwnPropertyNames(this).forEach((prop) => {
                         const item = this[prop];
-                        if (zod_helpers_1.ZodHelpers.isTranspilerableZodType(item) || zod_helpers_1.ZodHelpers.isZodArray(item)) {
+                        if (zod_helpers_1.ZodHelpers.isTranspilerableZodType(item) ||
+                            zod_helpers_1.ZodHelpers.isTranspilerableAliasedZodType(item, opt.basicTypes === false)) {
                             this[prop] = setMetadata(case_1.default.pascal(prop), item, opt);
                         }
                     });

package/dist/lib/zod_ext.d.ts

@@ -54,6 +54,12 @@ export interface IZod2xLayerMetadata {
      *   }
      */
     externalInheritance?: boolean;
+    /**
+     * Indicates if basic types (string, boolean, number, ...) shall be transpiled as aliases.
+     * If set to false, only complex types are transpiled (enum, object, array, union,
+     * intersection). Default is true.
+     */
+    basicTypes?: boolean;
 }
 export interface IZod2xMetadata {
     /**

package/dist/lib/zod_helpers.d.ts

@@ -35,7 +35,21 @@ export declare class ZodHelpers {
     static isZodAnyEnumType(i: ZodTypeAny): i is z.ZodEnum<any> | z.ZodNativeEnum<any>;
     static isZodAnyNumberType(i: ZodTypeAny): i is z.ZodNumber | z.ZodBigInt;
     static isZodAnyMapType(i: ZodTypeAny): i is z.ZodRecord<any, any> | z.ZodMap<any, any>;
+    /**
+     * Complex types that shall always be transpiled, which output would be a type, or alias if
+     * redefined using layered modeling.
+     * @param zodType
+     * @returns
+     */
     static isTranspilerableZodType(zodType: string | ZodTypeAny): boolean;
+    /**
+     * Primitive types that can only be transpiled if defined using layered modeling, which output
+     * would be a type alias.
+     * @param zodType
+     * @param onlyArray Array types are always transpiled as alias in layered modeling.
+     * @returns
+     */
+    static isTranspilerableAliasedZodType(zodType: string | ZodTypeAny, onlyArray?: boolean): boolean;
     static cloneZod(i: ZodTypeAny): any;
     static createZodObject(properties: Map<string, ZodTypeAny>): ZodObject<any>;
     static getZodNumberConstraints(i: ZodNumber | z.ZodBigInt): ZodNumberConstraints;

package/dist/lib/zod_helpers.js

@@ -84,6 +84,12 @@ class ZodHelpers {
     static isZodAnyMapType(i) {
         return this.isZodMap(i) || this.isZodRecord(i);
     }
+    /**
+     * Complex types that shall always be transpiled, which output would be a type, or alias if
+     * redefined using layered modeling.
+     * @param zodType
+     * @returns
+     */
     static isTranspilerableZodType(zodType) {
         var _a;
         const type = typeof zodType === "string" ? zodType : (_a = zodType === null || zodType === void 0 ? void 0 : zodType._def) === null || _a === void 0 ? void 0 : _a.typeName;
@@ -94,6 +100,31 @@ class ZodHelpers {
             type === zod_1.ZodFirstPartyTypeKind.ZodDiscriminatedUnion ||
             type === zod_1.ZodFirstPartyTypeKind.ZodIntersection);
     }
+    /**
+     * Primitive types that can only be transpiled if defined using layered modeling, which output
+     * would be a type alias.
+     * @param zodType
+     * @param onlyArray Array types are always transpiled as alias in layered modeling.
+     * @returns
+     */
+    static isTranspilerableAliasedZodType(zodType, onlyArray = false) {
+        var _a;
+        const type = typeof zodType === "string" ? zodType : (_a = zodType === null || zodType === void 0 ? void 0 : zodType._def) === null || _a === void 0 ? void 0 : _a.typeName;
+        if (onlyArray === true) {
+            return type === zod_1.ZodFirstPartyTypeKind.ZodArray;
+        }
+        return (type === zod_1.ZodFirstPartyTypeKind.ZodString ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodNumber ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodBigInt ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodBoolean ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodDate ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodAny ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodMap ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodSet ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodRecord ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodTuple ||
+            type === zod_1.ZodFirstPartyTypeKind.ZodArray);
+    }
     static cloneZod(i) {
         const zodType = i._def.typeName;
         return new zod_1.z[zodType](Object.assign({}, i._def));

package/dist/transpilers/cpp/runner.js

@@ -171,6 +171,9 @@ class Zod2Cpp extends core_1.Zod2X {
         if (data instanceof core_1.ASTArray) {
             extendedType = this.getAttributeType(data.item);
         }
+        else {
+            extendedType = this.getAttributeType(data);
+        }
         if (extendedType !== undefined) {
             this.push0(`using ${data.name} = ${extendedType};\n`);
         }

package/dist/transpilers/typescript/runner.js

@@ -96,6 +96,9 @@ class Zod2Ts extends core_1.Zod2X {
         if (data instanceof core_1.ASTArray) {
             extendedType = this.getAttributeType(data.item);
         }
+        else {
+            extendedType = this.getAttributeType(data);
+        }
         if (extendedType !== undefined) {
             this.push0(`export type ${data.name} = ${extendedType};\n`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zod-to-x",
-  "version": "1.4.6-dev.2",
+  "version": "1.4.6",
   "description": "Multi language types generation from Zod schemas.",
   "main": "dist/index.js",
   "files": [