@nestia/sdk 2.0.0-dev.20230831-4 → 2.0.0-dev.20230901

package/src/generates/internal/E2eFileProgrammer.ts

@@ -19,15 +19,6 @@ export namespace E2eFileProgrammer {
                         instance,
                     });
 
-            const additional: string[] = [];
-            for (const param of route.parameters.filter(
-                (p) => p.category !== "headers",
-            )) {
-                const type = getAdditional(param);
-                if (type === "uuid") additional.push(UUID);
-                else if (type === "date") additional.push(DATE);
-            }
-
             importer.internal({
                 type: false,
                 file: props.api,
@@ -39,7 +30,6 @@ export namespace E2eFileProgrammer {
                 importer.toScript(props.current),
                 "",
                 body,
-                ...(additional.length ? ["", ...additional] : []),
             ].join("\n");
 
             await fs.promises.writeFile(
@@ -53,7 +43,7 @@ export namespace E2eFileProgrammer {
         (config: INestiaConfig) =>
         (importer: ImportDictionary) =>
         (route: IRoute): string => {
-            const tab: number = route.output.name === "void" ? 2 : 3;
+            const tab: number = route.output.typeName === "void" ? 2 : 3;
             const headers = route.parameters.find(
                 (p) => p.category === "headers" && p.field === undefined,
             );
@@ -67,7 +57,7 @@ export namespace E2eFileProgrammer {
                           "        ...(connection.headers ?? {}),",
                           `        ...${SdkImportWizard.typia(
                               importer,
-                          )}.random<${headers.type.name}>(),`,
+                          )}.random<${headers.typeName}>(),`,
                           "    },",
                           "},",
                       ]
@@ -83,11 +73,11 @@ export namespace E2eFileProgrammer {
                 `export const ${name(route)} = async (`,
                 `    connection: api.IConnection`,
                 `): Promise<void> => {`,
-                ...(route.output.name === "void"
+                ...(route.output.typeName === "void"
                     ? [`    ${output}`]
                     : [
                           `    const output: ${primitive(config)(importer)(
-                              route.output.name,
+                              route.output.typeName,
                           )} = `,
                           `        ${output}`,
                           `    ${SdkImportWizard.typia(
@@ -103,16 +93,9 @@ export namespace E2eFileProgrammer {
         (importer: ImportDictionary) =>
         (tab: number) =>
         (param: IRoute.IParameter): string => {
-            const middle: string =
-                param.category === "param" &&
-                param.custom &&
-                (param.meta?.type === "uuid" || param.meta?.type === "date")
-                    ? param.meta.nullable
-                        ? `Math.random() < .2 ? null : ${param.meta.type}()`
-                        : `${param.meta.type}()`
-                    : `${SdkImportWizard.typia(importer)}.random<${primitive(
-                          config,
-                      )(importer)(param.type.name)}>()`;
+            const middle: string = `${SdkImportWizard.typia(
+                importer,
+            )}.random<${primitive(config)(importer)(param.typeName)}>()`;
             return `${" ".repeat(4 * tab)}${middle},`;
         };
 
@@ -129,29 +112,4 @@ export namespace E2eFileProgrammer {
             config.primitive !== false
                 ? `${SdkImportWizard.Primitive(importer)}<${name}>`
                 : name;
-
-    const getAdditional = (
-        param: IRoute.IParameter,
-    ): "uuid" | "date" | null => {
-        if (param.custom === false || param.category !== "param" || !param.meta)
-            return null;
-        else if (param.meta.type === "uuid") return "uuid";
-        else if (param.meta.type === "date") return "date";
-        return null;
-    };
 }
-
-const UUID = `const uuid = (): string =>
-    "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-        const r = (Math.random() * 16) | 0;
-        const v = c === "x" ? r : (r & 0x3) | 0x8;
-        return v.toString(16);
-    });`;
-const DATE = `const date = (): string => {
-    const date: Date = new Date(Math.floor(Math.random() * Date.now() * 2));
-    return [
-        date.getFullYear(),
-        (date.getMonth() + 1).toString().padStart(2, "0"),
-        date.getDate().toString().padStart(2, "0"),
-    ].join("-");
-}`;

package/src/generates/internal/SdkFunctionProgrammer.ts

@@ -1,6 +1,6 @@
 import { Pair } from "tstl/utility/Pair";
 
-import { IJsDocTagInfo } from "typia/lib/metadata/IJsDocTagInfo";
+import { IJsDocTagInfo } from "typia/lib/schemas/metadata/IJsDocTagInfo";
 import { Escaper } from "typia/lib/utils/Escaper";
 
 import { INestiaConfig } from "../../INestiaConfig";
@@ -283,7 +283,7 @@ export namespace SdkFunctionProgrammer {
                                 ? `${route.name}.${
                                       param === props.query ? "Query" : "Input"
                                   }`
-                                : param.type.name;
+                                : param.typeName;
                         return `${param.name}${
                             param.optional ? "?" : ""
                         }: ${type}`;
@@ -292,7 +292,9 @@ export namespace SdkFunctionProgrammer {
 
             // OUTPUT TYPE
             const output: string =
-                route.output.name === "void" ? "void" : `${route.name}.Output`;
+                route.output.typeName === "void"
+                    ? "void"
+                    : `${route.name}.Output`;
 
             // RETURNS WITH CONSTRUCTION
             return (
@@ -319,13 +321,13 @@ export namespace SdkFunctionProgrammer {
             // LIST UP TYPES
             const types: Pair<string, string>[] = [];
             if (props.headers !== undefined)
-                types.push(new Pair("Headers", props.headers.type.name));
+                types.push(new Pair("Headers", props.headers.typeName));
             if (props.query !== undefined)
-                types.push(new Pair("Query", props.query.type.name));
+                types.push(new Pair("Query", props.query.typeName));
             if (props.input !== undefined)
-                types.push(new Pair("Input", props.input.type.name));
-            if (route.output.name !== "void")
-                types.push(new Pair("Output", route.output.name));
+                types.push(new Pair("Input", props.input.typeName));
+            if (route.output.typeName !== "void")
+                types.push(new Pair("Output", route.output.typeName));
 
             // PATH WITH PARAMETERS
             const parameters: IRoute.IParameter[] = filter_path_parameters(
@@ -397,15 +399,15 @@ export namespace SdkFunctionProgrammer {
                         (param) =>
                             `${param.name}: ${
                                 param.category === "query" &&
-                                param.type.name === props.query?.type.name
+                                param.typeName === props.query?.typeName
                                     ? `${route.name}.Query`
-                                    : param.type.name
+                                    : param.typeName
                             }`,
                     )
                     .join(", ")}): string => {\n` +
                 `${path};\n` +
                 `    }\n` +
-                (config.simulate === true && route.output.name !== "void"
+                (config.simulate === true && route.output.typeName !== "void"
                     ? `    export const random = (g?: Partial<${SdkImportWizard.typia(
                           importer,
                       )}.IRandomGenerator>): Output =>\n` +

package/src/generates/internal/SdkSimulationProgrammer.ts

@@ -8,7 +8,7 @@ export namespace SdkSimulationProgrammer {
         (config: INestiaConfig) =>
         (importer: ImportDictionary) =>
         (route: IRoute): string => {
-            const output: boolean = route.output.name !== "void";
+            const output: boolean = route.output.typeName !== "void";
             const returns = () => [
                 `return random(`,
                 `    typeof connection.simulate === 'object' &&`,
@@ -28,7 +28,7 @@ export namespace SdkSimulationProgrammer {
                 `export const simulate = async (`,
                 `    ${
                     route.parameters.filter((p) => p.category !== "headers")
-                        .length === 0 && route.output.name === "void"
+                        .length === 0 && route.output.typeName === "void"
                         ? "_connection"
                         : "connection"
                 }: ${
@@ -52,7 +52,7 @@ export namespace SdkSimulationProgrammer {
                                               ? "Query"
                                               : "Input"
                                       }`
-                                    : p.type.name
+                                    : p.typeName
                             },`,
                     ),
                 `): Promise<${output ? "Output" : "void"}> => {`,
@@ -97,8 +97,8 @@ export namespace SdkSimulationProgrammer {
                             ? `assert.headers(() => ${SdkImportWizard.typia(
                                   importer,
                               )}.assert(connection.headers);` // not reachable
-                            : `assert.param("${p.field}")("${
-                                  p.custom && p.meta ? p.meta.type : p.type.name
+                            : `assert.param("${
+                                  p.field
                               }")(() => ${SdkImportWizard.typia(
                                   importer,
                               )}.assert(${p.name}));`,

package/src/generates/internal/SwaggerSchemaGenerator.ts

@@ -0,0 +1,433 @@
+import { Singleton } from "tstl";
+import ts from "typescript";
+
+import { IJsonSchema } from "typia";
+import { MetadataCollection } from "typia/lib/factories/MetadataCollection";
+import { MetadataFactory } from "typia/lib/factories/MetadataFactory";
+import { Metadata } from "typia/lib/schemas/metadata/Metadata";
+import { ValidationPipe } from "typia/lib/typings/ValidationPipe";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { IRoute } from "../../structures/IRoute";
+import { ISwaggerError } from "../../structures/ISwaggerError";
+import { ISwaggerRoute } from "../../structures/ISwaggerRoute";
+import { ISwaggerSchemaTuple } from "../../structures/ISwaggerSchemaTuple";
+import { SwaggerSchemaValidator } from "./SwaggerSchemaValidator";
+
+export namespace SwaggerSchemaGenerator {
+    export interface IProps {
+        config: INestiaConfig.ISwaggerConfig;
+        checker: ts.TypeChecker;
+        collection: MetadataCollection;
+        tuples: Array<ISwaggerSchemaTuple>;
+        errors: ISwaggerError[];
+    }
+
+    export const response =
+        (props: IProps) =>
+        (route: IRoute): ISwaggerRoute.IResponseBody => {
+            const output: ISwaggerRoute.IResponseBody = {};
+
+            //----
+            // EXCEPTION STATUSES
+            //----
+            // FROM DECORATOR
+            for (const [status, exp] of Object.entries(route.exceptions)) {
+                const result = MetadataFactory.analyze(props.checker)({
+                    escape: true,
+                    constant: true,
+                    absorb: false,
+                    validate: (meta) => {
+                        const bigint: boolean =
+                            meta.atomics.some((a) => a.type === "bigint") ||
+                            meta.constants.some((a) => a.type === "bigint");
+                        return bigint ? ["bigint type is not allowed."] : [];
+                    },
+                })(props.collection)(exp.type);
+                if (result.success === false)
+                    props.errors.push(
+                        ...result.errors.map((e) => ({
+                            ...e,
+                            route,
+                            from: `response body (status: ${status})`,
+                        })),
+                    );
+
+                output[status] = {
+                    description: exp.description ?? "",
+                    content: {
+                        "application/json": {
+                            schema: coalesceSchema(props)(result),
+                        },
+                    },
+                };
+            }
+
+            // FROM COMMENT TAGS -> ANY
+            for (const tag of route.tags) {
+                if (tag.name !== "throw" && tag.name !== "throws") continue;
+
+                const text: string | undefined = tag.text?.find(
+                    (elem) => elem.kind === "text",
+                )?.text;
+                if (text === undefined) continue;
+
+                const elements: string[] = text
+                    .split(" ")
+                    .map((str) => str.trim());
+                const status: string = elements[0];
+                if (
+                    isNaN(Number(status)) &&
+                    status !== "2XX" &&
+                    status !== "3XX" &&
+                    status !== "4XX" &&
+                    status !== "5XX"
+                )
+                    continue;
+
+                const description: string | undefined =
+                    elements.length === 1
+                        ? undefined
+                        : elements.slice(1).join(" ");
+                const oldbie = output[status];
+                if (description && oldbie !== undefined)
+                    oldbie.description = description;
+                else if (oldbie === undefined)
+                    output[status] = {
+                        description: description ?? "",
+                        content: {
+                            "application/json": {
+                                schema: {},
+                            },
+                        },
+                    };
+            }
+
+            //----
+            // SUCCESS
+            //----
+            // STATUS
+            const status: string =
+                route.status !== undefined
+                    ? String(route.status)
+                    : route.method === "GET" ||
+                      route.method === "HEAD" ||
+                      route.method === "DELETE"
+                    ? "200"
+                    : "201";
+
+            // SCHEMA
+            const result = MetadataFactory.analyze(props.checker)({
+                escape: true,
+                constant: true,
+                absorb: false,
+                validate: (meta) => {
+                    const bigint: boolean =
+                        meta.atomics.some((a) => a.type === "bigint") ||
+                        meta.constants.some((a) => a.type === "bigint");
+                    return bigint ? ["bigint type is not allowed."] : [];
+                },
+            })(props.collection)(route.output.type);
+            if (result.success === false)
+                props.errors.push(
+                    ...result.errors.map((e) => ({
+                        ...e,
+                        route,
+                        from: `response body (status: ${status})`,
+                    })),
+                );
+
+            // DO ASSIGN
+            const description =
+                describe(route, "return") ?? describe(route, "returns");
+            output[status] = {
+                description: route.encrypted
+                    ? `${warning
+                          .get(!!description)
+                          .get("response", route.method)}${description ?? ""}`
+                    : description ?? "",
+                content:
+                    route.output.typeName === "void"
+                        ? undefined
+                        : {
+                              [route.output.contentType]: {
+                                  schema: coalesceSchema(props)(result),
+                              },
+                          },
+                "x-nestia-encrypted": route.encrypted,
+            };
+            return output;
+        };
+
+    export const body =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (param: IRoute.IParameter): ISwaggerRoute.IRequestBody => {
+            // ANALZE TYPE WITH VALIDATION
+            const result = MetadataFactory.analyze(props.checker)({
+                escape: true,
+                constant: true,
+                absorb: true,
+                validate: (meta) => {
+                    const bigint: boolean =
+                        meta.atomics.some((a) => a.type === "bigint") ||
+                        meta.constants.some((a) => a.type === "bigint");
+                    return bigint ? ["bigint type is not allowed."] : [];
+                },
+            })(props.collection)(param.type);
+            if (result.success === false)
+                props.errors.push(
+                    ...result.errors.map((e) => ({
+                        ...e,
+                        route,
+                        from: `body parameter ${param.name}`,
+                    })),
+                );
+
+            // LIST UP PROPERTIES
+            const contentType =
+                param.custom && param.category === "body"
+                    ? param.contentType
+                    : "application/json";
+            const encrypted: boolean =
+                param.custom && param.category === "body" && param.encrypted;
+            const description: string | undefined = describe(
+                route,
+                "param",
+                param.name,
+            );
+
+            // RETURNS WITH LAZY CONSTRUCTION
+            const schema: IJsonSchema = coalesceSchema(props)(result);
+            return {
+                description: encrypted
+                    ? `${warning.get(!!description).get("request")}${
+                          description ?? ""
+                      }`
+                    : description,
+                content: {
+                    [contentType]: {
+                        schema,
+                    },
+                },
+                required: true,
+                "x-nestia-encrypted": encrypted,
+            };
+        };
+
+    export const parameter =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (param: IRoute.IParameter): ISwaggerRoute.IParameter =>
+            param.category === "headers"
+                ? headers(props)(route)(param)
+                : param.category === "param"
+                ? path(props)(route)(param)
+                : query(props)(route)(param);
+
+    const headers =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (param: IRoute.IParameter): ISwaggerRoute.IParameter => {
+            // ANALYZE TYPE WITH VALIDATIONS
+            const result = (() => {
+                const result = MetadataFactory.analyze(props.checker)({
+                    escape: false,
+                    constant: true,
+                    absorb: true,
+                })(props.collection)(param.type);
+                if (result.success === false)
+                    props.errors.push(
+                        ...result.errors.map((e) => ({
+                            ...e,
+                            route,
+                            from: `header parameter ${param.name}`,
+                        })),
+                    );
+                else if (result.data.objects.length === 1) {
+                    // WHEN OBJECT CASE, VALIDATE IT MORE DETAILY
+                    const again = MetadataFactory.analyze(props.checker)({
+                        escape: false,
+                        constant: true,
+                        absorb: true,
+                        validate: SwaggerSchemaValidator.headers,
+                    })(new MetadataCollection())(param.type);
+                    if (again.success === false) return again;
+                }
+                return result;
+            })();
+
+            // RETURNS WITH LAZY CONSTRUCTION
+            return lazyParameterReturns(props)(route)("header")(param, result);
+        };
+
+    const path =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (param: IRoute.IParameter): ISwaggerRoute.IParameter => {
+            // ANALZE TYPE WITH VALIDATION
+            const result = MetadataFactory.analyze(props.checker)({
+                escape: false,
+                constant: true,
+                absorb: true,
+                validate: SwaggerSchemaValidator.path,
+            })(props.collection)(param.type);
+            if (result.success === false)
+                props.errors.push(
+                    ...result.errors.map((e) => ({
+                        ...e,
+                        route,
+                        from: `path parameter ${param.name}`,
+                    })),
+                );
+
+            // RETURNS WITH LAZY CONSTRUCTION
+            return lazyParameterReturns(props)(route)("path")(param, result);
+        };
+
+    const query =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (param: IRoute.IParameter): ISwaggerRoute.IParameter => {
+            // ANALYZE TYPE WITH VALIDATIONS
+            const result = (() => {
+                const result = MetadataFactory.analyze(props.checker)({
+                    escape: false,
+                    constant: true,
+                    absorb: true,
+                })(props.collection)(param.type);
+                if (result.success === false) {
+                    props.errors.push(
+                        ...result.errors.map((e) => ({
+                            ...e,
+                            route,
+                            from: `query parameter ${param.name}`,
+                        })),
+                    );
+                } else if (result.data.objects.length === 1) {
+                    // WHEN OBJECT CASE, VALIDATE IT MORE DETAILY
+                    const again = MetadataFactory.analyze(props.checker)({
+                        escape: false,
+                        constant: true,
+                        absorb: true,
+                        validate: SwaggerSchemaValidator.query,
+                    })(new MetadataCollection())(param.type);
+                    if (again.success === false) return again;
+                }
+                return result;
+            })();
+
+            // RETURNS WITH LAZY CONSTRUCTION
+            return lazyParameterReturns(props)(route)("query")(param, result);
+        };
+
+    const coalesceSchema =
+        (props: IProps) =>
+        (
+            result: ValidationPipe<Metadata, MetadataFactory.IError>,
+        ): IJsonSchema => {
+            const schema: IJsonSchema = {} as any;
+            props.tuples.push({
+                metadata: result.success ? result.data : any.get(),
+                schema,
+            });
+            return schema;
+        };
+
+    const lazyParameterReturns =
+        (props: IProps) =>
+        (route: IRoute) =>
+        (inKeyword: string) =>
+        (
+            param: IRoute.IParameter,
+            result: ValidationPipe<Metadata, MetadataFactory.IError>,
+        ) => {
+            const schema: IJsonSchema = coalesceSchema(props)(result);
+            return {
+                name: param.field ?? param.name,
+                in: inKeyword,
+                schema,
+                description: describe(route, "param", param.name) ?? "",
+                required: result.success ? result.data.isRequired() : true,
+            };
+        };
+
+    function describe(
+        route: IRoute,
+        tagName: string,
+        parameterName?: string,
+    ): string | undefined {
+        const parametric: (elem: ts.JSDocTagInfo) => boolean = parameterName
+            ? (tag) =>
+                  tag.text!.find(
+                      (elem) =>
+                          elem.kind === "parameterName" &&
+                          elem.text === parameterName,
+                  ) !== undefined
+            : () => true;
+
+        const tag: ts.JSDocTagInfo | undefined = route.tags.find(
+            (tag) => tag.name === tagName && tag.text && parametric(tag),
+        );
+        return tag && tag.text
+            ? tag.text.find((elem) => elem.kind === "text")?.text
+            : undefined;
+    }
+}
+
+const warning = new Singleton((described: boolean) => {
+    return new Singleton((type: "request" | "response", method?: string) => {
+        const summary =
+            type === "request"
+                ? "Request body must be encrypted."
+                : "Response data have been encrypted.";
+        const component =
+            type === "request"
+                ? "[EncryptedBody](https://github.com/samchon/@nestia/core#encryptedbody)"
+                : `[EncryptedRoute.${method![0].toUpperCase()}.${method!
+                      .substring(1)
+                      .toLowerCase()}](https://github.com/samchon/@nestia/core#encryptedroute)`;
+
+        const content: string[] = [
+            "## Warning",
+            "",
+            summary,
+            "",
+            `The ${type} body data would be encrypted as "AES-128(256) / CBC mode / PKCS#5 Padding / Base64 Encoding", through the ${component} component.`,
+            "",
+            `Therefore, just utilize this swagger editor only for referencing. If you need to call the real API, using [SDK](https://github.com/samchon/nestia#software-development-kit) would be much better.`,
+        ];
+        if (described === true) content.push("----------------", "");
+        return content.join("\n");
+    });
+});
+
+const any = new Singleton(() =>
+    Metadata.from(
+        {
+            any: true,
+            required: true,
+            optional: false,
+            nullable: false,
+            functional: false,
+            atomics: [],
+            constants: [],
+            templates: [],
+            escaped: null,
+            rest: null,
+            arrays: [],
+            tuples: [],
+            objects: [],
+            aliases: [],
+            natives: [],
+            sets: [],
+            maps: [],
+        },
+        {
+            aliases: [],
+            arrays: [],
+            tuples: [],
+            objects: [],
+        },
+    ),
+);