@nestia/sdk 1.1.1 → 1.2.0-dev.20230504-2

package/src/generates/internal/SdkFileProgrammer.ts

@@ -0,0 +1,144 @@
+import fs from "fs";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { IRoute } from "../../structures/IRoute";
+import { ImportDictionary } from "../../utils/ImportDictionary";
+import { SdkFunctionProgrammer } from "./SdkFunctionProgrammer";
+import { SdkRouteDirectory } from "./SdkRouteDirectory";
+
+export namespace SdkFileProgrammer {
+    /* ---------------------------------------------------------
+        CONSTRUCTOR
+    --------------------------------------------------------- */
+    export const generate =
+        (config: INestiaConfig) =>
+        async (routeList: IRoute[]): Promise<void> => {
+            // CONSTRUCT FOLDER TREE
+            const root: SdkRouteDirectory = new SdkRouteDirectory(
+                null,
+                "functional",
+            );
+            for (const route of routeList) emplace(root)(route);
+
+            // RELOCATE FOR ONLY ONE CONTROLLER METHOD IN AN URL CASE
+            relocate(root);
+
+            // ITERATE FILES
+            await iterate(config)(root)(config.output + "/functional");
+        };
+
+    const emplace =
+        (directory: SdkRouteDirectory) =>
+        (route: IRoute): void => {
+            // SEPARATE IDENTIFIERS
+            const identifiers: string[] = route.path
+                .split("/")
+                .filter((str) => str.length && str[0] !== ":")
+                .map((str) => str.split("-").join("_").split(".").join("_"));
+
+            // OPEN DIRECTORIES
+            for (const key of identifiers) {
+                directory = directory.directories.take(
+                    key,
+                    () => new SdkRouteDirectory(directory, key),
+                );
+            }
+
+            // ADD ROUTE
+            directory.routes.push(route);
+        };
+
+    const relocate = (directory: SdkRouteDirectory): void => {
+        if (
+            directory.parent !== null &&
+            directory.directories.empty() &&
+            directory.routes.length === 1 &&
+            directory.name === directory.routes[0].name
+        ) {
+            directory.parent.routes.push(directory.routes[0]);
+            directory.parent.directories.erase(directory.name);
+        } else if (directory.directories.empty() === false)
+            for (const it of directory.directories) relocate(it.second);
+    };
+
+    /* ---------------------------------------------------------
+        FILE ITERATOR
+    --------------------------------------------------------- */
+    const iterate =
+        (config: INestiaConfig) =>
+        (directory: SdkRouteDirectory) =>
+        async (outDir: string): Promise<void> => {
+            // CREATE A NEW DIRECTORY
+            try {
+                await fs.promises.mkdir(outDir);
+            } catch {}
+
+            // ITERATE CHILDREN
+            const content: string[] = [];
+            for (const it of directory.directories) {
+                await iterate(config)(it.second)(`${outDir}/${it.first}`);
+                content.push(`export * as ${it.first} from "./${it.first}";`);
+            }
+            if (content.length && directory.routes.length) content.push("");
+
+            // ITERATE ROUTES
+            const importDict: ImportDictionary = new ImportDictionary();
+            directory.routes.forEach((route, i) => {
+                for (const tuple of route.imports)
+                    for (const instance of tuple[1])
+                        importDict.emplace(tuple[0], false, instance);
+
+                content.push(SdkFunctionProgrammer.generate(config)(route));
+                if (i !== directory.routes.length - 1) content.push("");
+            });
+
+            // FINALIZE THE CONTENT
+            if (directory.routes.length !== 0) {
+                const primitived: boolean =
+                    config.primitive !== false &&
+                    directory.routes.some(
+                        (route) =>
+                            route.output.name !== "void" ||
+                            route.parameters.some(
+                                (param) => param.category !== "param",
+                            ),
+                    );
+                const asserted: boolean =
+                    config.assert === true &&
+                    directory.routes.some(
+                        (route) => route.parameters.length !== 0,
+                    );
+                const json: boolean =
+                    config.json === true &&
+                    directory.routes.some(
+                        (route) =>
+                            route.method === "POST" ||
+                            route.method === "PUT" ||
+                            route.method === "PATCH",
+                    );
+
+                const fetcher: string[] = ["Fetcher"];
+                if (primitived) fetcher.push("Primitive");
+
+                const head: string[] = [
+                    `import { ${fetcher.join(", ")} } from "@nestia/fetcher";`,
+                    `import type { IConnection } from "@nestia/fetcher";`,
+                ];
+                if (asserted || json) head.push(`import typia from "typia";`);
+                if (!importDict.empty())
+                    head.push("", importDict.toScript(outDir));
+
+                content.push(...head, "", ...content.splice(0, content.length));
+            }
+
+            const script: string =
+                "/**\n" +
+                " * @packageDocumentation\n" +
+                ` * @module ${directory.module}\n` +
+                " * @nestia Generated by Nestia - https://github.com/samchon/nestia \n" +
+                " */\n" +
+                "//================================================================\n" +
+                content.join("\n");
+            await fs.promises.writeFile(`${outDir}/index.ts`, script, "utf8");
+        };
+}

package/src/generates/internal/SdkFunctionProgrammer.ts

@@ -0,0 +1,371 @@
+import { Vector } from "tstl/container/Vector";
+import { Pair } from "tstl/utility/Pair";
+import ts from "typescript";
+
+import { Escaper } from "typia/lib/utils/Escaper";
+
+import { INestiaConfig } from "../../INestiaConfig";
+import { IRoute } from "../../structures/IRoute";
+
+export namespace SdkFunctionProgrammer {
+    export const generate =
+        (config: INestiaConfig) =>
+        (route: IRoute): string => {
+            const query: IRoute.IParameter | undefined = route.parameters.find(
+                (param) =>
+                    param.category === "query" && param.field === undefined,
+            );
+            const input: IRoute.IParameter | undefined = route.parameters.find(
+                (param) => param.category === "body",
+            );
+
+            return [head, body, tail]
+                .map((closure) => closure(config)(route)({ query, input }))
+                .filter((str) => !!str)
+                .join("\n");
+        };
+
+    /* ---------------------------------------------------------
+        BODY
+    --------------------------------------------------------- */
+    const body =
+        (config: INestiaConfig) =>
+        (route: IRoute) =>
+        (props: {
+            query: IRoute.IParameter | undefined;
+            input: IRoute.IParameter | undefined;
+        }): string => {
+            // FETCH ARGUMENTS WITH REQUST BODY
+            const parameters = filter_parameters(route)(props.query);
+            const fetchArguments: string[] = [
+                "connection",
+                `${route.name}.ENCRYPTED`,
+                `${route.name}.METHOD`,
+                `${route.name}.path(${parameters
+                    .map((p) => p.name)
+                    .join(", ")})`,
+            ];
+            if (props.input !== undefined) {
+                fetchArguments.push(props.input.name);
+                if (config.json === true)
+                    fetchArguments.push(`${route.name}.stringify`);
+            }
+
+            const assertions: string =
+                config.assert === true && route.parameters.length !== 0
+                    ? route.parameters
+                          .map(
+                              (param) =>
+                                  `    typia.assert<typeof ${param.name}>(${param.name});`,
+                          )
+                          .join("\n") + "\n\n"
+                    : "";
+
+            // FUNCTION CALL STATEMENT
+            const caller: string =
+                "Fetcher.fetch\n" +
+                "    (\n" +
+                fetchArguments.map((param) => `        ${param}`).join(",\n") +
+                "\n" +
+                "    )";
+            if (route.setHeaders.length === 0)
+                return `{\n${assertions}    return ${caller};\n}`;
+
+            // SET HEADERS
+            const content: string[] = [
+                `{\n`,
+                assertions,
+                `    const output: ${route.name}.Output = await ${caller};\n`,
+                "\n",
+                `    // configure header(s)\n`,
+                `    connection.headers ??= {};\n`,
+            ];
+
+            for (const header of route.setHeaders) {
+                if (header.type === "assigner")
+                    content.push(
+                        "    ",
+                        `Object.assign(connection.headers, ${access("output")(
+                            header.source,
+                        )});\n`,
+                    );
+                else
+                    content.push(
+                        "    ",
+                        `${access("connection.headers")(
+                            header.target ?? header.source,
+                        )} = ${access("output")(header.source)};\n`,
+                    );
+            }
+            content.push("\n", "    return output;\n", "}");
+            return content.join("");
+        };
+
+    const filter_parameters =
+        (route: IRoute) =>
+        (query: IRoute.IParameter | undefined): IRoute.IParameter[] => {
+            const parameters: IRoute.IParameter[] = route.parameters.filter(
+                (param) =>
+                    param.category === "param" ||
+                    (param.category === "query" && param.field !== undefined),
+            );
+            if (query) parameters.push(query);
+            return parameters;
+        };
+
+    const access =
+        (x: string) =>
+        (y: string): string =>
+            y[0] === "[" ? `${x}${y}` : `${x}.${y}`;
+
+    /* ---------------------------------------------------------
+        HEAD & TAIL
+    --------------------------------------------------------- */
+    const head =
+        (config: INestiaConfig) =>
+        (route: IRoute) =>
+        (props: {
+            query: IRoute.IParameter | undefined;
+            input: IRoute.IParameter | undefined;
+        }): string => {
+            //----
+            // CONSTRUCT COMMENT
+            //----
+            // MAIN DESCRIPTION
+            const comments: string[] = route.comments
+                .map(
+                    (part) =>
+                        `${part.kind === "linkText" ? " " : ""}${part.text}`,
+                )
+                .map((str) => str.split("\r\n").join("\n"))
+                .join("")
+                .split("\n")
+                .filter(
+                    (str, i, array) => str !== "" || i !== array.length - 1,
+                );
+            if (comments.length) comments.push("");
+
+            // FILTER TAGS (VULNERABLE PARAMETERS WOULD BE REMOVED)
+            const tagList: ts.JSDocTagInfo[] = route.tags.slice();
+            if (tagList.length !== 0) {
+                const index: number = tagList.findIndex(
+                    (t) => t.name === "param",
+                );
+                if (index !== -1) {
+                    const capsule: Vector<ts.JSDocTagInfo> =
+                        Vector.wrap(tagList);
+                    capsule.insert(capsule.nth(index), {
+                        name: "param",
+                        text: [
+                            {
+                                kind: "parameterName",
+                                text: "connection",
+                            },
+                            {
+                                kind: "space",
+                                text: " ",
+                            },
+                            {
+                                kind: "text",
+                                text: "connection Information of the remote HTTP(s) server with headers (+encryption password)",
+                            },
+                        ],
+                    });
+                }
+                comments.push(
+                    ...tagList.map((tag) =>
+                        tag.text
+                            ? `@${tag.name} ${tag.text
+                                  .map((elem) => elem.text)
+                                  .join("")}`
+                            : `@${tag.name}`,
+                    ),
+                    "",
+                );
+            }
+
+            // COMPLETE THE COMMENT
+            comments.push(
+                `@controller ${route.symbol}`,
+                `@path ${route.method} ${route.path}`,
+                `@nestia Generated by Nestia - https://github.com/samchon/nestia`,
+            );
+
+            //----
+            // FINALIZATION
+            //----
+            // REFORM PARAMETERS TEXT
+            const parameters: string[] = [
+                "connection: IConnection",
+                ...route.parameters.map((param) => {
+                    const type: string =
+                        config.primitive !== false &&
+                        (param === props.query || param === props.input)
+                            ? `Primitive<${route.name}.${
+                                  param === props.query ? "Query" : "Input"
+                              }>`
+                            : param.type.name;
+                    return `${param.name}${param.optional ? "?" : ""}: ${type}`;
+                }),
+            ];
+
+            // OUTPUT TYPE
+            const output: string =
+                route.output.name === "void" ? "void" : `${route.name}.Output`;
+
+            // RETURNS WITH CONSTRUCTION
+            return (
+                "" +
+                "/**\n" +
+                comments.map((str) => ` * ${str}`).join("\n") +
+                "\n" +
+                " */\n" +
+                `export${route.setHeaders.length ? " async" : ""} function ${
+                    route.name
+                }\n` +
+                `    (\n` +
+                `${parameters.map((str) => `        ${str}`).join(",\n")}\n` +
+                `    ): Promise<${output}>`
+            );
+        };
+
+    const tail =
+        (config: INestiaConfig) =>
+        (route: IRoute) =>
+        (props: {
+            query: IRoute.IParameter | undefined;
+            input: IRoute.IParameter | undefined;
+        }): string | null => {
+            // LIST UP TYPES
+            const types: Pair<string, string>[] = [];
+            if (props.query !== undefined)
+                types.push(new Pair("Query", props.query.type.name));
+            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));
+
+            // PATH WITH PARAMETERS
+            const parameters: IRoute.IParameter[] = filter_parameters(route)(
+                props.query,
+            );
+            const path: string = compute_path({
+                path: route.path,
+                query: props.query,
+                parameters,
+            });
+
+            return (
+                `export namespace ${route.name}\n` +
+                "{\n" +
+                (types.length !== 0
+                    ? types
+                          .map(
+                              (tuple) =>
+                                  `    export type ${tuple.first} = ${
+                                      config.primitive !== false
+                                          ? `Primitive<${tuple.second}>`
+                                          : tuple.second
+                                  };`,
+                          )
+                          .join("\n") + "\n"
+                    : "") +
+                "\n" +
+                `    export const METHOD = "${route.method}" as const;\n` +
+                `    export const PATH: string = "${route.path}";\n` +
+                `    export const ENCRYPTED: Fetcher.IEncrypted = {\n` +
+                `        request: ${
+                    props.input !== undefined && props.input.encrypted
+                },\n` +
+                `        response: ${route.encrypted},\n` +
+                (route.status !== undefined
+                    ? `        status: ${route.status},\n`
+                    : "") +
+                `    };\n` +
+                "\n" +
+                `    export function path(${parameters
+                    .map((param) => `${param.name}: ${param.type.name}`)
+                    .join(", ")}): string\n` +
+                `    {\n` +
+                `${path};\n` +
+                `    }\n` +
+                (config.json === true &&
+                route.parameters.find((param) => param.category === "body") !==
+                    undefined
+                    ? `    export const stringify = (input: Input) => typia.assertStringify(input);\n`
+                    : "") +
+                "}"
+            );
+        };
+
+    const compute_path = (props: {
+        query: IRoute.IParameter | undefined;
+        parameters: IRoute.IParameter[];
+        path: string;
+    }): string => {
+        for (const param of props.parameters)
+            if (param.category === "param")
+                props.path = props.path.replace(
+                    `:${param.field}`,
+                    `\${encodeURIComponent(${param.name} ?? "null")}`,
+                );
+
+        // NO QUERY PARAMETER
+        const queryParams: IRoute.IParameter[] = props.parameters.filter(
+            (param) => param.category === "query" && param.field !== undefined,
+        );
+        if (props.query === undefined && queryParams.length === 0)
+            return `${" ".repeat(8)}return \`${props.path}\``;
+
+        const computeName = (str: string): string =>
+            props.parameters.find((p) => p.name === str) !== undefined
+                ? computeName("_" + str)
+                : str;
+        const variables: string = computeName("variables");
+        const search: string = computeName("search");
+        const encoded: string = computeName("encoded");
+
+        const wrapper = (expr: string) =>
+            [
+                `const ${variables}: Record<any, any> = ${expr};`,
+                `const ${search}: URLSearchParams = new URLSearchParams();`,
+                `for (const [key, value] of Object.entries(${variables}))`,
+                `    if (value === undefined) continue;`,
+                `    else if (Array.isArray(value))`,
+                `        value.forEach((elem) => ${search}.append(key, String(elem)));`,
+                `    else`,
+                `        ${search}.set(key, String(value));`,
+                `const ${encoded}: string = ${search}.toString();`,
+                `return \`${props.path}\${${encoded}.length ? \`?\${${encoded}}\` : ""}\`;`,
+            ]
+                .map((str) => `${" ".repeat(8)}${str}`)
+                .join("\n");
+
+        if (props.query !== undefined && queryParams.length === 0)
+            return wrapper(`${props.query.name} as any`);
+        else if (props.query === undefined)
+            return wrapper(`
+        {
+            ${rest_query_parameters(queryParams)}
+        } as any`);
+
+        return wrapper(`
+        {
+            ...${props.query.name},
+            ${rest_query_parameters(queryParams)},
+        } as any`);
+    };
+
+    const rest_query_parameters = (parameters: IRoute.IParameter[]): string =>
+        parameters
+            .map((param) =>
+                param.name === param.field
+                    ? param.name
+                    : `${
+                          Escaper.variable(param.field!)
+                              ? param.field
+                              : JSON.stringify(param.field)
+                      }: ${param.name}`,
+            )
+            .join(`,\n${" ".repeat(12)}`);
+}

package/src/generates/internal/SdkRouteDirectory.ts

@@ -0,0 +1,21 @@
+import { HashMap } from "tstl";
+
+import { IRoute } from "../../structures/IRoute";
+
+export class SdkRouteDirectory {
+    public readonly module: string;
+    public readonly directories: HashMap<string, SdkRouteDirectory>;
+    public readonly routes: IRoute[];
+
+    public constructor(
+        readonly parent: SdkRouteDirectory | null,
+        readonly name: string,
+    ) {
+        this.directories = new HashMap();
+        this.routes = [];
+        this.module =
+            this.parent !== null
+                ? `${this.parent.module}.${name}`
+                : `api.${name}`;
+    }
+}

package/src/structures/IController.ts

@@ -23,5 +23,9 @@ export namespace IController {
         field: string | undefined;
         category: ParamCategory;
         encrypted: boolean;
+        meta?: {
+            type: string;
+            nullable: boolean;
+        };
     }
 }

package/src/structures/IRoute.ts

@@ -31,5 +31,9 @@ export namespace IRoute {
         encrypted: boolean;
         type: ITypeTuple;
         optional: boolean;
+        meta?: {
+            type: string;
+            nullable: boolean;
+        };
     }
 }

package/src/utils/NestiaConfigUtil.ts

@@ -0,0 +1,21 @@
+import { INestiaConfig } from "../INestiaConfig";
+
+export namespace NestiaConfigUtil {
+    export const input = (
+        config: INestiaConfig["input"],
+    ): INestiaConfig.IInput =>
+        Array.isArray(config)
+            ? {
+                  include: config,
+                  exclude: [],
+              }
+            : typeof config === "object"
+            ? {
+                  include: config.include,
+                  exclude: config.exclude ?? [],
+              }
+            : {
+                  include: [config],
+                  exclude: [],
+              };
+}

package/src/utils/SourceFinder.ts

@@ -0,0 +1,60 @@
+import fs from "fs";
+import glob from "glob";
+import path from "path";
+
+export namespace SourceFinder {
+    export const find = async (props: IProps): Promise<string[]> => {
+        const dict: Set<string> = new Set();
+
+        await emplace(props.filter)(props.include)((str) => dict.add(str));
+        if (props.exclude?.length)
+            await emplace(props.filter)(props.exclude)((str) =>
+                dict.delete(str),
+            );
+
+        return [...dict];
+    };
+
+    const emplace =
+        (filter: (file: string) => boolean) =>
+        (input: string[]) =>
+        async (closure: (location: string) => void): Promise<void> => {
+            for (const pattern of input) {
+                for (const file of await _Glob(path.resolve(pattern))) {
+                    const stats: fs.Stats = await fs.promises.stat(file);
+                    if (stats.isDirectory() === true)
+                        await iterate(filter)(closure)(file);
+                    else if (stats.isFile() && filter(file)) closure(file);
+                }
+            }
+        };
+
+    const iterate =
+        (filter: (location: string) => boolean) =>
+        (closure: (location: string) => void) =>
+        async (location: string): Promise<void> => {
+            const directory: string[] = await fs.promises.readdir(location);
+            for (const file of directory) {
+                const next: string = path.resolve(`${location}/${file}`);
+                const stats: fs.Stats = await fs.promises.stat(next);
+
+                if (stats.isDirectory() === true)
+                    await iterate(filter)(closure)(next);
+                else if (stats.isFile() && filter(next)) closure(next);
+            }
+        };
+
+    const _Glob = (pattern: string): Promise<string[]> =>
+        new Promise((resolve, reject) => {
+            glob(pattern, (err, matches) => {
+                if (err) reject(err);
+                else resolve(matches.map((str) => path.resolve(str)));
+            });
+        });
+}
+
+interface IProps {
+    exclude?: string[];
+    include: string[];
+    filter: (location: string) => boolean;
+}

package/lib/analyses/SourceFinder.d.ts

@@ -1,4 +0,0 @@
-import { INestiaConfig } from "../INestiaConfig";
-export declare namespace SourceFinder {
-    function find(input: INestiaConfig.IInput): Promise<string[]>;
-}