@nestia/sdk 2.0.0-dev.20230904-2 → 2.0.0-dev.20230906

package/src/generates/internal/SdkDtoGenerator.ts

@@ -0,0 +1,384 @@
+import fs from "fs";
+import ts from "typescript";
+
+import { MetadataCollection } from "typia/lib/factories/MetadataCollection";
+import { MetadataFactory } from "typia/lib/factories/MetadataFactory";
+import { IJsDocTagInfo } from "typia/lib/schemas/metadata/IJsDocTagInfo";
+import { IMetadataTypeTag } from "typia/lib/schemas/metadata/IMetadataTypeTag";
+import { Metadata } from "typia/lib/schemas/metadata/Metadata";
+import { MetadataAlias } from "typia/lib/schemas/metadata/MetadataAlias";
+import { MetadataArray } from "typia/lib/schemas/metadata/MetadataArray";
+import { MetadataAtomic } from "typia/lib/schemas/metadata/MetadataAtomic";
+import { MetadataConstant } from "typia/lib/schemas/metadata/MetadataConstant";
+import { MetadataObject } from "typia/lib/schemas/metadata/MetadataObject";
+import { MetadataProperty } from "typia/lib/schemas/metadata/MetadataProperty";
+import { MetadataTuple } from "typia/lib/schemas/metadata/MetadataTuple";
+import { Escaper } from "typia/lib/utils/Escaper";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { IRoute } from "../../structures/IRoute";
+import { ImportDictionary } from "../../utils/ImportDictionary";
+import { MapUtil } from "../../utils/MapUtil";
+
+export namespace SdkDtoGenerator {
+    export const generate =
+        (checker: ts.TypeChecker) =>
+        (config: INestiaConfig) =>
+        async (routes: IRoute[]): Promise<void> => {
+            try {
+                await fs.promises.mkdir(`${config.output}/structures`);
+            } catch {}
+
+            const collection = new MetadataCollection({
+                replace: MetadataCollection.replace,
+            });
+            for (const r of routes) {
+                for (const p of r.parameters) {
+                    const res = MetadataFactory.analyze(checker)({
+                        escape: false,
+                        constant: true,
+                        absorb: false,
+                    })(collection)(p.type);
+                    if (res.success) p.metadata = res.data;
+                }
+                const res = MetadataFactory.analyze(checker)({
+                    escape: true,
+                    constant: true,
+                    absorb: false,
+                })(collection)(r.output.type);
+                if (res.success) r.output.metadata = res.data;
+            }
+
+            const modules: Map<string, IModule> = new Map();
+            for (const alias of collection.aliases())
+                prepare(modules)(alias.name)((importer) =>
+                    defineAlias(config)(importer)(alias),
+                );
+            for (const object of collection.objects())
+                prepare(modules)(object.name)((importer) =>
+                    defineObject(config)(importer)(object),
+                );
+
+            for (const module of modules.values())
+                await generateFile(config)(module);
+        };
+
+    const prepare =
+        (dict: Map<string, IModule>) =>
+        (name: string) =>
+        (programmer: (importer: ImportDictionary) => string) => {
+            const accessors: string[] = name.split(".");
+            let module: IModule;
+
+            accessors.forEach((acc, i) => {
+                module = MapUtil.take(dict, acc, () => ({
+                    name: accessors.slice(0, i + 1).join("."),
+                    children: new Map(),
+                }));
+                module.programmer = programmer;
+                dict = module.children;
+            });
+            return module!;
+        };
+
+    const generateFile =
+        (config: INestiaConfig) =>
+        async (module: IModule): Promise<void> => {
+            const importer: ImportDictionary = new ImportDictionary();
+
+            const body: string = writeModule(importer)(module);
+            const content: string[] = [];
+            if (!importer.empty())
+                content.push(
+                    importer.toScript(`${config.output}/structures`),
+                    "",
+                );
+            content.push(body);
+
+            const location: string = `${config.output}/structures/${module.name}.ts`;
+            await fs.promises.writeFile(location, content.join("\n"), "utf8");
+        };
+
+    const writeModule =
+        (importer: ImportDictionary) =>
+        (module: IModule): string => {
+            const content: string[] = [];
+            if (module.programmer) content.push(module.programmer(importer));
+            if (module.children.size) {
+                content.push(
+                    `export namespace ${module.name.split(".").at(-1)} {`,
+                );
+                for (const child of module.children.values())
+                    content.push(
+                        writeModule(importer)(child)
+                            .split("\n")
+                            .map((l) => `    ${l}`)
+                            .join("\n"),
+                    );
+                content.push("}");
+            }
+            return content.join("\n");
+        };
+
+    const defineAlias =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (alias: MetadataAlias) =>
+            [
+                ...writeComment(alias.description, alias.jsDocTags),
+                `export type ${alias.name.split(".").pop()!} = ${decode(config)(
+                    importer,
+                )(alias.value)};`,
+            ].join("\n");
+
+    const defineObject =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (object: MetadataObject) => {
+            const top: string = [
+                ...writeComment(object.description ?? null, object.jsDocTags),
+                `export type ${object.name.split(".").pop()!} = `,
+            ].join("\n");
+            if (object.properties.length === 0) return top + "{};";
+
+            const regular: MetadataProperty[] = object.properties.filter((p) =>
+                p.key.isSoleLiteral(),
+            );
+            const dynamic: MetadataProperty[] = object.properties.filter(
+                (p) => !p.key.isSoleLiteral(),
+            );
+
+            const brackets: string[][] = [];
+            if (regular.length) {
+                const row: string[] = ["{"];
+                for (const p of regular) {
+                    const key: string = p.key.constants[0].values[0] as string;
+                    const identifier: string = Escaper.variable(key)
+                        ? key
+                        : JSON.stringify(key);
+                    row.push(
+                        ...writeComment(p.description, p.jsDocTags).map(
+                            (l) => `    ${l}`,
+                        ),
+                        `    ${identifier}: ${decode(config)(importer)(
+                            p.value,
+                        )};`,
+                    );
+                }
+                row.push("}");
+                brackets.push(row);
+            }
+            for (const p of dynamic) {
+                const row: string[] = ["{"];
+                row.push(
+                    ...writeComment(p.description, p.jsDocTags).map(
+                        (l) => `    ${l}`,
+                    ),
+                    `    [key: ${decode(config)(importer)(p.key)}]: ${decode(
+                        config,
+                    )(importer)(p.value)};`,
+                );
+                row.push("}");
+                brackets.push(row);
+            }
+            return top + brackets.map((row) => row.join("\n")).join(" & ");
+        };
+
+    const writeComment = (
+        description: string | null,
+        jsDocTags: IJsDocTagInfo[],
+    ): string[] => {
+        const lines: string[] = [];
+        if (description?.length)
+            lines.push(...description.split("\n").map((s) => `${s}`));
+        if (description?.length && jsDocTags?.length) lines.push("");
+        if (jsDocTags?.length)
+            lines.push(
+                ...jsDocTags.map((t) =>
+                    t.text?.length
+                        ? `@${t.name} ${t.text.map((e) => e.text).join("")}`
+                        : `@${t.name}`,
+                ),
+            );
+        if (lines.length === 0) return [];
+        return ["/**", ...lines.map((s) => ` * ${s}`), " */"];
+    };
+
+    export const decode =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (meta: Metadata): string => {
+            const union: string[] = [];
+
+            // COALESCES
+            if (meta.nullable) union.push("null");
+            if (meta.required === false) union.push("undefined");
+
+            // ATOMICS
+            for (const atomic of meta.atomics)
+                union.push(decodeAtomic(importer)(atomic));
+            for (const constant of meta.constants)
+                union.push(decodeConstant(constant));
+            for (const tpl of meta.templates)
+                union.push(decodeTemplate(config)(importer)(tpl));
+
+            // ARRAYS
+            for (const array of meta.arrays)
+                union.push(decodeArray(config)(importer)(array));
+            for (const tuple of meta.tuples)
+                union.push(decodeTuple(config)(importer)(tuple));
+
+            // OBJECTS
+            for (const obj of meta.objects)
+                union.push(decodeObject(config)(importer)(obj));
+            for (const alias of meta.aliases)
+                union.push(decodeAlias(config)(importer)(alias));
+
+            return union.join(" | ");
+        };
+
+    const decodeTypeTag =
+        (importer: ImportDictionary) =>
+        (tag: IMetadataTypeTag): string => {
+            const front: string = tag.name.split("<")[0];
+            if (NATIVE_TYPE_TAGS.has(front)) {
+                importer.external({
+                    type: true,
+                    library: `typia/lib/tags/${front}`,
+                    instance: front,
+                });
+                return tag.name;
+            }
+            importer.external({
+                type: true,
+                library: `typia/lib/tags/TagBase`,
+                instance: "TagBase",
+            });
+            return `TagBase<${JSON.stringify(tag)}>`;
+        };
+
+    const decodeTypeTagMatrix =
+        (importer: ImportDictionary) =>
+        (base: string, tags: IMetadataTypeTag[][]): string => {
+            if (tags.length === 0) return base;
+            else if (tags.length === 1)
+                return `(${base} & ${tags[0]
+                    .map((t) => decodeTypeTag(importer)(t))
+                    .join(" & ")})`;
+            return (
+                "(" +
+                [
+                    base,
+                    ...tags.map(
+                        (row) =>
+                            `(${row
+                                .map((t) => decodeTypeTag(importer)(t))
+                                .join(" & ")})`,
+                    ),
+                ] +
+                ")"
+            );
+        };
+
+    const decodeAtomic =
+        (importer: ImportDictionary) =>
+        (atomic: MetadataAtomic): string =>
+            decodeTypeTagMatrix(importer)(atomic.type, atomic.tags);
+
+    const decodeTemplate =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (template: Metadata[]): string =>
+            "`" +
+            template
+                .map((meta) =>
+                    meta.size() === 1 &&
+                    meta.isRequired() &&
+                    meta.nullable === false &&
+                    meta.constants.length === 1
+                        ? String(meta.constants[0].values[0])
+                              .split("`")
+                              .join("\\`")
+                        : `\${${decode(config)(importer)(meta)}}`,
+                )
+                .join("") +
+            "`";
+
+    const decodeConstant = (constant: MetadataConstant): string => {
+        if (constant.values.length === 0)
+            return JSON.stringify(constant.values[0]);
+        return `(${constant.values
+            .map((val) => JSON.stringify(val))
+            .join(" | ")})`;
+    };
+
+    const decodeArray =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (array: MetadataArray): string =>
+            decodeTypeTagMatrix(importer)(
+                `Array<${decode(config)(importer)(array.type.value)}>`,
+                array.tags,
+            );
+
+    const decodeTuple =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (tuple: MetadataTuple): string =>
+            "[" +
+            tuple.type.elements.map((e) =>
+                e.rest
+                    ? `...${decode(config)(importer)(e.rest)}`
+                    : decode(config)(importer)(e),
+            ) +
+            "]";
+
+    const decodeAlias =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (alias: MetadataAlias) => {
+            importInternalFile(config)(importer)(alias.name);
+            return alias.name;
+        };
+
+    const decodeObject =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (object: MetadataObject) => {
+            importInternalFile(config)(importer)(object.name);
+            return object.name;
+        };
+
+    const importInternalFile =
+        (config: INestiaConfig) =>
+        (importer: ImportDictionary) =>
+        (name: string) => {
+            const top = name.split(".")[0];
+            importer.internal({
+                type: true,
+                file: `${config.output}/structures/${name.split(".")[0]}`,
+                instance: top,
+            });
+        };
+}
+
+const NATIVE_TYPE_TAGS = new Set([
+    "ExclusiveMinimum",
+    "ExclusiveMaximum",
+    "Format",
+    "Maximum",
+    "MaxItems",
+    "MaxLength",
+    "Minimum",
+    "MinItems",
+    "MinLength",
+    "MultipleOf",
+    "Pattern",
+    "Type",
+]);
+
+interface IModule {
+    name: string;
+    children: Map<string, IModule>;
+    programmer?: (importer: ImportDictionary) => string;
+}

package/src/generates/internal/SdkFileProgrammer.ts

@@ -73,13 +73,14 @@ export namespace SdkFileProgrammer {
                     type: false,
                 });
             directory.routes.forEach((route, i) => {
-                for (const tuple of route.imports)
-                    for (const instance of tuple[1])
-                        importer.internal({
-                            file: tuple[0],
-                            instance,
-                            type: true,
-                        });
+                if (config.clone !== true)
+                    for (const tuple of route.imports)
+                        for (const instance of tuple[1])
+                            importer.internal({
+                                file: tuple[0],
+                                instance,
+                                type: true,
+                            });
 
                 content.push(
                     SdkFunctionProgrammer.generate(config)(importer)(route),

package/src/generates/internal/SdkFunctionProgrammer.ts

@@ -7,6 +7,7 @@ import { INestiaConfig } from "../../INestiaConfig";
 import { IController } from "../../structures/IController";
 import { IRoute } from "../../structures/IRoute";
 import { ImportDictionary } from "../../utils/ImportDictionary";
+import { SdkDtoGenerator } from "./SdkDtoGenerator";
 import { SdkImportWizard } from "./SdkImportWizard";
 import { SdkSimulationProgrammer } from "./SdkSimulationProgrammer";
 
@@ -221,7 +222,7 @@ export namespace SdkFunctionProgrammer {
                 : [];
 
             // COMMENT TAGS
-            const tags: IJsDocTagInfo[] = route.tags.filter(
+            const tags: IJsDocTagInfo[] = route.jsDocTags.filter(
                 (tag) =>
                     tag.name !== "param" ||
                     route.parameters
@@ -283,7 +284,7 @@ export namespace SdkFunctionProgrammer {
                                 ? `${route.name}.${
                                       param === props.query ? "Query" : "Input"
                                   }`
-                                : param.typeName;
+                                : getTypeName(config)(importer)(param);
                         return `${param.name}${
                             param.optional ? "?" : ""
                         }: ${type}`;
@@ -321,13 +322,33 @@ export namespace SdkFunctionProgrammer {
             // LIST UP TYPES
             const types: Pair<string, string>[] = [];
             if (props.headers !== undefined)
-                types.push(new Pair("Headers", props.headers.typeName));
+                types.push(
+                    new Pair(
+                        "Headers",
+                        getTypeName(config)(importer)(props.headers),
+                    ),
+                );
             if (props.query !== undefined)
-                types.push(new Pair("Query", props.query.typeName));
+                types.push(
+                    new Pair(
+                        "Query",
+                        getTypeName(config)(importer)(props.query),
+                    ),
+                );
             if (props.input !== undefined)
-                types.push(new Pair("Input", props.input.typeName));
+                types.push(
+                    new Pair(
+                        "Input",
+                        getTypeName(config)(importer)(props.input),
+                    ),
+                );
             if (route.output.typeName !== "void")
-                types.push(new Pair("Output", route.output.typeName));
+                types.push(
+                    new Pair(
+                        "Output",
+                        getTypeName(config)(importer)(route.output),
+                    ),
+                );
 
             // PATH WITH PARAMETERS
             const parameters: IRoute.IParameter[] = filter_path_parameters(
@@ -401,7 +422,7 @@ export namespace SdkFunctionProgrammer {
                                 param.category === "query" &&
                                 param.typeName === props.query?.typeName
                                     ? `${route.name}.Query`
-                                    : param.typeName
+                                    : getTypeName(config)(importer)(param)
                             }`,
                     )
                     .join(", ")}): string => {\n` +
@@ -507,3 +528,10 @@ export namespace SdkFunctionProgrammer {
 }
 
 const space = (count: number) => " ".repeat(count);
+const getTypeName =
+    (config: INestiaConfig) =>
+    (importer: ImportDictionary) =>
+    (p: IRoute.IParameter | IRoute.IOutput) =>
+        p.metadata
+            ? SdkDtoGenerator.decode(config)(importer)(p.metadata)
+            : p.typeName;

package/src/generates/internal/SdkSimulationProgrammer.ts

@@ -1,6 +1,7 @@
 import { INestiaConfig } from "../../INestiaConfig";
 import { IRoute } from "../../structures/IRoute";
 import { ImportDictionary } from "../../utils/ImportDictionary";
+import { SdkDtoGenerator } from "./SdkDtoGenerator";
 import { SdkImportWizard } from "./SdkImportWizard";
 
 export namespace SdkSimulationProgrammer {
@@ -52,7 +53,7 @@ export namespace SdkSimulationProgrammer {
                                               ? "Query"
                                               : "Input"
                                       }`
-                                    : p.typeName
+                                    : getTypeName(config)(importer)(p)
                             },`,
                     ),
                 `): Promise<${output ? "Output" : "void"}> => {`,
@@ -106,3 +107,11 @@ export namespace SdkSimulationProgrammer {
             ];
         };
 }
+
+const getTypeName =
+    (config: INestiaConfig) =>
+    (importer: ImportDictionary) =>
+    (p: IRoute.IParameter | IRoute.IOutput) =>
+        p.metadata
+            ? SdkDtoGenerator.decode(config)(importer)(p.metadata)
+            : p.typeName;

package/src/generates/internal/SwaggerSchemaGenerator.ts

@@ -64,7 +64,7 @@ export namespace SwaggerSchemaGenerator {
             }
 
             // FROM COMMENT TAGS -> ANY
-            for (const tag of route.tags) {
+            for (const tag of route.jsDocTags) {
                 if (tag.name !== "throw" && tag.name !== "throws") continue;
 
                 const text: string | undefined = tag.text?.find(
@@ -363,7 +363,7 @@ export namespace SwaggerSchemaGenerator {
                   ) !== undefined
             : () => true;
 
-        const tag: ts.JSDocTagInfo | undefined = route.tags.find(
+        const tag: ts.JSDocTagInfo | undefined = route.jsDocTags.find(
             (tag) => tag.name === tagName && tag.text && parametric(tag),
         );
         return tag && tag.text

package/src/structures/IController.ts

@@ -6,6 +6,7 @@ export interface IController {
     paths: string[];
     functions: IController.IFunction[];
     security: Record<string, string[]>[];
+    swaggerTgas: string[];
 }
 
 export namespace IController {
@@ -23,6 +24,7 @@ export namespace IController {
             number | "2XX" | "3XX" | "4XX" | "5XX",
             IController.IException
         >;
+        swaggerTags: string[];
     }
 
     export type IParameter =

package/src/structures/IRoute.ts

@@ -1,5 +1,7 @@
 import ts from "typescript";
 
+import { Metadata } from "typia/lib/schemas/metadata/Metadata";
+
 import { IController } from "./IController";
 
 export interface IRoute {
@@ -18,16 +20,17 @@ export interface IRoute {
     symbol: {
         class: string;
         function: string;
-    }
+    };
     description?: string;
     operationId?: string;
-    tags: ts.JSDocTagInfo[];
+    jsDocTags: ts.JSDocTagInfo[];
     setHeaders: Array<
         | { type: "setter"; source: string; target?: string }
         | { type: "assigner"; source: string }
     >;
     security: Record<string, string[]>[];
     exceptions: Record<number | "2XX" | "3XX" | "4XX" | "5XX", IRoute.IOutput>;
+    swaggerTags: string[];
 }
 
 export namespace IRoute {
@@ -35,10 +38,12 @@ export namespace IRoute {
         optional: boolean;
         type: ts.Type;
         typeName: string;
+        metadata?: Metadata;
     };
     export interface IOutput {
         type: ts.Type;
         typeName: string;
+        metadata?: Metadata;
         description?: string;
         contentType: "application/json" | "text/plain";
     }