@nestia/sdk 0.1.0

package/src/generates/SwaggerGenerator.ts

@@ -0,0 +1,393 @@
+import fs from "fs";
+import NodePath from "path";
+import { Singleton } from "tstl/thread/Singleton";
+import { VariadicSingleton } from "tstl/thread/VariadicSingleton";
+import ts from "typescript";
+import { IJsonApplication, IJsonSchema } from "typia";
+import { CommentFactory } from "typia/lib/factories/CommentFactory";
+import { MetadataCollection } from "typia/lib/factories/MetadataCollection";
+import { MetadataFactory } from "typia/lib/factories/MetadataFactory";
+import { Metadata } from "typia/lib/metadata/Metadata";
+import { ApplicationProgrammer } from "typia/lib/programmers/ApplicationProgrammer";
+
+import { INestiaConfig } from "../INestiaConfig";
+import { IRoute } from "../structures/IRoute";
+import { ISwagger } from "../structures/ISwagger";
+import { MapUtil } from "../utils/MapUtil";
+
+export namespace SwaggerGenerator {
+    export async function generate(
+        checker: ts.TypeChecker,
+        config: INestiaConfig.ISwagger,
+        routeList: IRoute[],
+    ): Promise<void> {
+        // PREPARE ASSETS
+        const parsed: NodePath.ParsedPath = NodePath.parse(config.output);
+        const location: string = !!parsed.ext
+            ? NodePath.resolve(config.output)
+            : NodePath.join(NodePath.resolve(config.output), "swagger.json");
+
+        const collection: MetadataCollection = new MetadataCollection({
+            replace: MetadataCollection.replace,
+        });
+
+        // CONSTRUCT SWAGGER DOCUMENTS
+        const tupleList: Array<ISchemaTuple> = [];
+        const swagger: ISwagger = await initialize(location);
+        const pathDict: Map<string, ISwagger.IPath> = new Map();
+
+        for (const route of routeList) {
+            const path: ISwagger.IPath = MapUtil.take(
+                pathDict,
+                get_path(route.path, route.parameters),
+                () => ({}),
+            );
+            path[route.method.toLowerCase()] = generate_route(
+                checker,
+                collection,
+                tupleList,
+                route,
+            );
+        }
+        swagger.paths = {};
+        for (const [path, routes] of pathDict) {
+            swagger.paths[path] = routes;
+        }
+
+        // FILL JSON-SCHEMAS
+        const application: IJsonApplication = ApplicationProgrammer.generate(
+            tupleList.map(({ metadata }) => metadata),
+            {
+                purpose: "swagger",
+            },
+        );
+        swagger.components = {
+            ...(swagger.components || {}),
+            schemas: application.components.schemas,
+        };
+        tupleList.forEach(({ schema }, index) => {
+            Object.assign(schema, application.schemas[index]!);
+        });
+
+        // ERASE IJsonComponents.IObject.$id
+        for (const obj of Object.values(swagger.components.schemas))
+            if (obj.$id) delete obj.$id;
+
+        // DO GENERATE
+        await fs.promises.writeFile(
+            location,
+            JSON.stringify(swagger, null, 2),
+            "utf8",
+        );
+    }
+
+    /* ---------------------------------------------------------
+        INITIALIZERS
+    --------------------------------------------------------- */
+    async function initialize(path: string): Promise<ISwagger> {
+        // LOAD OR CREATE NEW SWAGGER DATA
+        const swagger: ISwagger = fs.existsSync(path)
+            ? JSON.parse(await fs.promises.readFile(path, "utf8"))
+            : {
+                  openapi: "3.0.1",
+                  servers: [
+                      {
+                          url: "https://github.com/samchon/nestia",
+                          description: "insert your server url",
+                      },
+                  ],
+                  info: {
+                      version: "0.1.0",
+                      title: "Generated by nestia - https://github.com/samchon/nestia",
+                  },
+                  paths: {},
+                  components: {},
+              };
+
+        // RETURNS
+        return swagger;
+    }
+
+    function get_path(path: string, parameters: IRoute.IParameter[]): string {
+        const filtered: IRoute.IParameter[] = parameters.filter(
+            (param) => param.category === "param" && !!param.field,
+        );
+        for (const param of filtered)
+            path = path.replace(`:${param.field}`, `{${param.field}}`);
+        return path;
+    }
+
+    function generate_route(
+        checker: ts.TypeChecker,
+        collection: MetadataCollection,
+        tupleList: Array<ISchemaTuple>,
+        route: IRoute,
+    ): ISwagger.IRoute {
+        const bodyParam = route.parameters.find(
+            (param) => param.category === "body",
+        );
+        const tags: string[] = route.tags
+            .filter(
+                (tag) =>
+                    tag.name === "tag" &&
+                    tag.text &&
+                    tag.text.find(
+                        (elem) => elem.kind === "text" && elem.text.length,
+                    ) !== undefined,
+            )
+            .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
+
+        const encrypted: boolean =
+            route.encrypted === true ||
+            !!route.parameters.find((param) => param.encrypted === true);
+        return {
+            tags,
+            summary: encrypted ? "encrypted" : undefined,
+            parameters: route.parameters
+                .filter((param) => param.category !== "body")
+                .map((param) =>
+                    generate_parameter(
+                        checker,
+                        collection,
+                        tupleList,
+                        route,
+                        param,
+                    ),
+                ),
+            requestBody: bodyParam
+                ? generate_request_body(
+                      checker,
+                      collection,
+                      tupleList,
+                      route,
+                      bodyParam,
+                  )
+                : undefined,
+            responses: generate_response_body(
+                checker,
+                collection,
+                tupleList,
+                route,
+            ),
+            description: CommentFactory.generate(route.comments),
+        };
+    }
+
+    /* ---------------------------------------------------------
+        REQUEST & RESPONSE
+    --------------------------------------------------------- */
+    function generate_parameter(
+        checker: ts.TypeChecker,
+        collection: MetadataCollection,
+        tupleList: Array<ISchemaTuple>,
+        route: IRoute,
+        parameter: IRoute.IParameter,
+    ): ISwagger.IParameter {
+        const schema: IJsonSchema | null = generate_schema(
+            checker,
+            collection,
+            tupleList,
+            parameter.type.type,
+        );
+        if (schema === null)
+            throw new Error(
+                `Error on NestiaApplication.sdk(): invalid parameter type on ${route.symbol}#${parameter.name}`,
+            );
+
+        return {
+            name: parameter.field || parameter.name,
+            in: parameter.category === "param" ? "path" : parameter.category,
+            description:
+                get_parametric_description(route, "param", parameter.name) ||
+                "",
+            schema,
+            required: true,
+        };
+    }
+
+    function generate_request_body(
+        checker: ts.TypeChecker,
+        collection: MetadataCollection,
+        tupleList: Array<ISchemaTuple>,
+        route: IRoute,
+        parameter: IRoute.IParameter,
+    ): ISwagger.IRequestBody {
+        const schema: IJsonSchema | null = generate_schema(
+            checker,
+            collection,
+            tupleList,
+            parameter.type.type,
+        );
+        if (schema === null)
+            throw new Error(
+                `Error on NestiaApplication.sdk(): invalid request body type on ${route.symbol}.`,
+            );
+
+        return {
+            description:
+                warning.get(parameter.encrypted).get("request") +
+                (get_parametric_description(route, "param", parameter.name) ||
+                    ""),
+            content: {
+                "application/json": {
+                    schema,
+                },
+            },
+            required: true,
+        };
+    }
+
+    function generate_response_body(
+        checker: ts.TypeChecker,
+        collection: MetadataCollection,
+        tupleList: Array<ISchemaTuple>,
+        route: IRoute,
+    ): ISwagger.IResponseBody {
+        // OUTPUT WITH SUCCESS STATUS
+        const status: string =
+            route.method === "GET" || route.method === "DELETE" ? "200" : "201";
+        const schema: IJsonSchema | null = generate_schema(
+            checker,
+            collection,
+            tupleList,
+            route.output.type,
+        );
+        const success: ISwagger.IResponseBody = {
+            [status]: {
+                description:
+                    warning.get(route.encrypted).get("response", route.method) +
+                    (get_parametric_description(route, "return") ||
+                        get_parametric_description(route, "returns") ||
+                        ""),
+                content:
+                    schema === null || route.output.name === "void"
+                        ? undefined
+                        : {
+                              "application/json": {
+                                  schema,
+                              },
+                          },
+            },
+        };
+
+        // EXCEPTION STATUSES
+        const exceptions: ISwagger.IResponseBody = Object.fromEntries(
+            route.tags
+                .filter(
+                    (tag) =>
+                        tag.name === "throw" &&
+                        tag.text &&
+                        tag.text.find(
+                            (elem) =>
+                                elem.kind === "text" &&
+                                isNaN(
+                                    Number(
+                                        elem.text
+                                            .split(" ")
+                                            .map((str) => str.trim())[0],
+                                    ),
+                                ) === false,
+                        ) !== undefined,
+                )
+                .map((tag) => {
+                    const text: string = tag.text!.find(
+                        (elem) => elem.kind === "text",
+                    )!.text;
+                    const elements: string[] = text
+                        .split(" ")
+                        .map((str) => str.trim());
+
+                    return [
+                        elements[0],
+                        {
+                            description: elements.slice(1).join(" "),
+                        },
+                    ];
+                }),
+        );
+        return { ...exceptions, ...success };
+    }
+
+    /* ---------------------------------------------------------
+        UTILS
+    --------------------------------------------------------- */
+    function generate_schema(
+        checker: ts.TypeChecker,
+        collection: MetadataCollection,
+        tupleList: Array<ISchemaTuple>,
+        type: ts.Type,
+    ): IJsonSchema | null {
+        const metadata: Metadata = MetadataFactory.generate(
+            checker,
+            collection,
+            type,
+            {
+                resolve: false,
+                constant: true,
+            },
+        );
+        if (metadata.empty() && metadata.nullable === false) return null;
+
+        const schema: IJsonSchema = {} as IJsonSchema;
+        tupleList.push({ metadata, schema });
+        return schema;
+    }
+
+    function get_parametric_description(
+        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 VariadicSingleton((encrypted: boolean) => {
+    if (encrypted === false) return new Singleton(() => "");
+
+    return new VariadicSingleton(
+        (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)`;
+
+            return `## 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.
+
+-----------------
+
+`;
+        },
+    );
+});
+
+interface ISchemaTuple {
+    metadata: Metadata;
+    schema: IJsonSchema;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import * as nestia from "./module";
+
+export default nestia;

package/src/module.ts

@@ -0,0 +1,2 @@
+export * from "./INestiaConfig";
+export * from "./NestiaSdkApplication";

package/src/structures/IController.ts

@@ -0,0 +1,27 @@
+import { ParamCategory } from "./ParamCategory";
+
+export interface IController {
+    file: string;
+    name: string;
+    paths: string[];
+    functions: IController.IFunction[];
+}
+
+export namespace IController {
+    export interface IFunction {
+        name: string;
+        method: string;
+        paths: string[];
+        encrypted: boolean;
+
+        parameters: IParameter[];
+    }
+
+    export interface IParameter {
+        name: string;
+        index: number;
+        field: string | undefined;
+        category: ParamCategory;
+        encrypted: boolean;
+    }
+}

package/src/structures/IRoute.ts

@@ -0,0 +1,29 @@
+import ts from "typescript";
+
+import { ITypeTuple } from "./ITypeTuple";
+import { ParamCategory } from "./ParamCategory";
+
+export interface IRoute {
+    name: string;
+    method: string;
+    path: string;
+    encrypted: boolean;
+
+    parameters: IRoute.IParameter[];
+    imports: [string, string[]][];
+    output: ITypeTuple;
+
+    symbol: string;
+    comments: ts.SymbolDisplayPart[];
+    tags: ts.JSDocTagInfo[];
+}
+
+export namespace IRoute {
+    export interface IParameter {
+        name: string;
+        field: string | undefined;
+        category: ParamCategory;
+        encrypted: boolean;
+        type: ITypeTuple;
+    }
+}

package/src/structures/ISwagger.ts

@@ -0,0 +1,55 @@
+import { IJsonComponents, IJsonSchema } from "typia";
+
+export interface ISwagger {
+    openapi: "3.0";
+    servers: ISwagger.IServer[];
+    info: ISwagger.IInfo;
+    paths: Record<string, ISwagger.IPath>;
+    components: IJsonComponents;
+}
+export namespace ISwagger {
+    export type IPath = Record<string, IRoute>;
+    export interface IRoute {
+        description: string;
+        tags: string[];
+        parameters: IParameter[];
+        responses: IResponseBody;
+        requestBody?: IRequestBody;
+        summary?: string;
+    }
+
+    export interface IInfo {
+        version: string;
+        title: string;
+    }
+    export interface IParameter {
+        name: string;
+        in: string;
+        schema: IJsonSchema;
+        required: true;
+        description: string;
+    }
+    export interface IRequestBody {
+        description: string;
+        content: IJsonContent;
+        required: true;
+    }
+    export type IResponseBody = Record<
+        string,
+        {
+            description: string;
+            content?: IJsonContent;
+        }
+    >;
+
+    export interface IServer {
+        url: string;
+        description?: string;
+    }
+
+    export interface IJsonContent {
+        "application/json": {
+            schema: IJsonSchema;
+        };
+    }
+}

package/src/structures/ITypeTuple.ts

@@ -0,0 +1,6 @@
+import ts from "typescript";
+
+export interface ITypeTuple {
+    type: ts.Type;
+    name: string;
+}

package/src/structures/MethodType.ts

@@ -0,0 +1,11 @@
+export type MethodType = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export namespace MethodType {
+    export const VALUES: MethodType[] = [
+        "GET",
+        "POST",
+        "PUT",
+        "PATCH",
+        "DELETE",
+    ];
+}

package/src/structures/ParamCategory.ts

@@ -0,0 +1 @@
+export type ParamCategory = "param" | "query" | "body";

package/src/structures/TypeEntry.ts

@@ -0,0 +1,22 @@
+import { hash } from "tstl/functional/hash";
+import ts from "typescript";
+
+export class TypeEntry {
+    public constructor(
+        public readonly type: ts.Type,
+        public readonly nullable: boolean,
+        public readonly required: boolean,
+    ) {}
+
+    public equals(obj: TypeEntry): boolean {
+        return (
+            this.type === obj.type &&
+            this.nullable === obj.nullable &&
+            this.required === obj.required
+        );
+    }
+
+    public hashCode(): number {
+        return hash(this.type, this.nullable, this.required);
+    }
+}

package/src/utils/ArrayUtil.ts

@@ -0,0 +1,26 @@
+export namespace ArrayUtil {
+    export function has<T>(array: T[], ...items: T[]): boolean {
+        return items.every(
+            (elem) => array.find((org) => org === elem) !== undefined,
+        );
+    }
+
+    export async function asyncMap<Input, Output>(
+        array: Input[],
+        closure: (input: Input) => Promise<Output>,
+    ): Promise<Output[]> {
+        const ret: Output[] = [];
+        for (const elem of array) ret.push(await closure(elem));
+        return ret;
+    }
+
+    export async function asyncFilter<Input>(
+        array: Input[],
+        closure: (input: Input) => Promise<boolean>,
+    ): Promise<Input[]> {
+        const ret: Input[] = [];
+        for (const elem of array)
+            if ((await closure(elem)) === true) ret.push(elem);
+        return ret;
+    }
+}

package/src/utils/ImportDictionary.ts

@@ -0,0 +1,56 @@
+import path from "path";
+import { HashMap } from "tstl/container/HashMap";
+import { HashSet } from "tstl/container/HashSet";
+import { Pair } from "tstl/utility/Pair";
+
+export class ImportDictionary {
+    private readonly dict_: HashMap<string, Pair<boolean, HashSet<string>>> =
+        new HashMap();
+
+    public empty(): boolean {
+        return this.dict_.empty();
+    }
+
+    public emplace(file: string, realistic: boolean, instance: string): void {
+        if (file.substr(-5) === ".d.ts") file = file.substr(0, file.length - 5);
+        else if (file.substr(-3) === ".ts")
+            file = file.substr(0, file.length - 3);
+        else
+            throw new Error(
+                `Error on ImportDictionary.emplace(): extension of the target file "${file}" is not "ts".`,
+            );
+
+        const pair: Pair<boolean, HashSet<string>> = this.dict_.take(
+            file,
+            () => new Pair(realistic, new HashSet()),
+        );
+        pair.second.insert(instance);
+    }
+
+    public toScript(outDir: string): string {
+        const statements: string[] = [];
+        for (const it of this.dict_) {
+            const file: string = (() => {
+                const location: string = path
+                    .relative(outDir, it.first)
+                    .split("\\")
+                    .join("/");
+                const index: number = location.lastIndexOf(NODE_MODULES);
+                return index === -1
+                    ? `./${location}`
+                    : location.substring(index + NODE_MODULES.length);
+            })();
+            const realistic: boolean = it.second.first;
+            const instances: string[] = it.second.second.toJSON();
+
+            statements.push(
+                `import ${!realistic ? "type " : ""}{ ${instances.join(
+                    ", ",
+                )} } from "${file}";`,
+            );
+        }
+        return statements.join("\n");
+    }
+}
+
+const NODE_MODULES = "node_modules/";

package/src/utils/MapUtil.ts

@@ -0,0 +1,14 @@
+export namespace MapUtil {
+    export function take<Key, T>(
+        dict: Map<Key, T>,
+        key: Key,
+        generator: () => T,
+    ): T {
+        const oldbie: T | undefined = dict.get(key);
+        if (oldbie) return oldbie;
+
+        const value: T = generator();
+        dict.set(key, value);
+        return value;
+    }
+}

package/src/utils/StripEnums.ts

@@ -0,0 +1,10 @@
+export type StripEnums<T extends Record<string, any>> = {
+    [Key in keyof T]: T[Key] extends
+        | string
+        | boolean
+        | object
+        | undefined
+        | any[]
+        ? T[Key]
+        : any;
+};