@nestia/sdk 0.1.0

package/src/analyses/ControllerAnalyzer.ts

@@ -0,0 +1,203 @@
+import { HashMap } from "tstl/container/HashMap";
+import ts from "typescript";
+
+import { IController } from "../structures/IController";
+import { IRoute } from "../structures/IRoute";
+import { ITypeTuple } from "../structures/ITypeTuple";
+import { GenericAnalyzer } from "./GenericAnalyzer";
+import { ImportAnalyzer } from "./ImportAnalyzer";
+import { PathAnalyzer } from "./PathAnalyzer";
+
+export namespace ControllerAnalyzer {
+    export function analyze(
+        checker: ts.TypeChecker,
+        sourceFile: ts.SourceFile,
+        controller: IController,
+    ): IRoute[] {
+        // FIND CONTROLLER CLASS
+        const ret: IRoute[] = [];
+        ts.forEachChild(sourceFile, (node) => {
+            if (
+                ts.isClassDeclaration(node) &&
+                node.name?.escapedText === controller.name
+            ) {
+                // ANALYZE THE CONTROLLER
+                ret.push(..._Analyze_controller(checker, controller, node));
+                return;
+            }
+        });
+        return ret;
+    }
+
+    /* ---------------------------------------------------------
+        CLASS
+    --------------------------------------------------------- */
+    function _Analyze_controller(
+        checker: ts.TypeChecker,
+        controller: IController,
+        classNode: ts.ClassDeclaration,
+    ): IRoute[] {
+        const classType: ts.InterfaceType = checker.getTypeAtLocation(
+            classNode,
+        ) as ts.InterfaceType;
+        const genericDict: GenericAnalyzer.Dictionary = GenericAnalyzer.analyze(
+            checker,
+            classNode,
+        );
+
+        const ret: IRoute[] = [];
+        for (const property of classType.getProperties()) {
+            // GET METHOD DECLARATION
+            const declaration: ts.Declaration | undefined =
+                (property.declarations || [])[0];
+            if (!declaration || !ts.isMethodDeclaration(declaration)) continue;
+
+            // IDENTIFIER MUST BE
+            const identifier = declaration.name;
+            if (!ts.isIdentifier(identifier)) continue;
+
+            // ANALYZED WITH THE REFLECTED-FUNCTION
+            const runtime: IController.IFunction | undefined =
+                controller.functions.find(
+                    (f) => f.name === identifier.escapedText,
+                );
+            if (runtime === undefined) continue;
+
+            const routes: IRoute[] = _Analyze_function(
+                checker,
+                controller,
+                genericDict,
+                runtime,
+                property,
+            );
+            ret.push(...routes);
+        }
+        return ret;
+    }
+
+    /* ---------------------------------------------------------
+        FUNCTION
+    --------------------------------------------------------- */
+    function _Analyze_function(
+        checker: ts.TypeChecker,
+        controller: IController,
+        genericDict: GenericAnalyzer.Dictionary,
+        func: IController.IFunction,
+        symbol: ts.Symbol,
+    ): IRoute[] {
+        // PREPARE ASSETS
+        const type: ts.Type = checker.getTypeOfSymbolAtLocation(
+            symbol,
+            symbol.valueDeclaration!,
+        );
+        const signature: ts.Signature | undefined = checker.getSignaturesOfType(
+            type,
+            ts.SignatureKind.Call,
+        )[0];
+
+        if (signature === undefined)
+            throw new Error(
+                `Error on ControllerAnalyzer.analyze(): unable to get the signature from the ${controller.name}.${func.name}().`,
+            );
+
+        const importDict: ImportAnalyzer.Dictionary = new HashMap();
+
+        // EXPLORE CHILDREN TYPES
+        const parameters: IRoute.IParameter[] = func.parameters.map((param) =>
+            _Analyze_parameter(
+                checker,
+                genericDict,
+                importDict,
+                controller,
+                func.name,
+                param,
+                signature.getParameters()[param.index],
+            ),
+        );
+        const output: ITypeTuple = ImportAnalyzer.analyze(
+            checker,
+            genericDict,
+            importDict,
+            signature.getReturnType(),
+        );
+        const imports: [string, string[]][] = importDict
+            .toJSON()
+            .map((pair) => [pair.first, pair.second.toJSON()]);
+
+        // CONSTRUCT COMMON DATA
+        const common: Omit<IRoute, "path"> = {
+            ...func,
+            parameters,
+            output,
+            imports,
+
+            symbol: `${controller.name}.${func.name}()`,
+            comments: signature.getDocumentationComment(undefined),
+            tags: signature.getJsDocTags(),
+        };
+
+        // CONFIGURE PATHS
+        const pathList: string[] = [];
+        for (const controllerPath of controller.paths)
+            for (const filePath of func.paths) {
+                const path: string = PathAnalyzer.join(
+                    controllerPath,
+                    filePath,
+                );
+                pathList.push(
+                    PathAnalyzer.espace(
+                        path,
+                        () => "ControllerAnalyzer.analyze()",
+                    ),
+                );
+            }
+
+        // RETURNS
+        return pathList.map((path) => ({
+            ...common,
+            path,
+        }));
+    }
+
+    /* ---------------------------------------------------------
+        PARAMETER
+    --------------------------------------------------------- */
+    function _Analyze_parameter(
+        checker: ts.TypeChecker,
+        genericDict: GenericAnalyzer.Dictionary,
+        importDict: ImportAnalyzer.Dictionary,
+        controller: IController,
+        funcName: string,
+        param: IController.IParameter,
+        symbol: ts.Symbol,
+    ): IRoute.IParameter {
+        const type: ts.Type = checker.getTypeOfSymbolAtLocation(
+            symbol,
+            symbol.valueDeclaration!,
+        );
+        const name: string = symbol.getEscapedName().toString();
+
+        // DO NOT SUPPORT BODY PARAMETER
+        if (param.category === "body" && param.field !== undefined) {
+            const method: string = `${controller.name}.${funcName}()`;
+            throw new Error(
+                `Error on ${method}: nestia does not support body field specification. ` +
+                    `Therefore, erase the ${method}#${name} parameter and ` +
+                    `re-define a new body decorator accepting full structured message.`,
+            );
+        }
+
+        return {
+            name,
+            category: param.category,
+            field: param.field,
+            encrypted: param.encrypted,
+            type: ImportAnalyzer.analyze(
+                checker,
+                genericDict,
+                importDict,
+                type,
+            ),
+        };
+    }
+}

package/src/analyses/GenericAnalyzer.ts

@@ -0,0 +1,53 @@
+import ts from "typescript";
+
+export namespace GenericAnalyzer {
+    export type Dictionary = WeakMap<ts.Type, ts.Type>;
+
+    export function analyze(
+        checker: ts.TypeChecker,
+        classNode: ts.ClassDeclaration,
+    ): Dictionary {
+        const dict: Dictionary = new WeakMap();
+        explore(checker, dict, classNode);
+        return dict;
+    }
+
+    function explore(
+        checker: ts.TypeChecker,
+        dict: Dictionary,
+        classNode: ts.ClassDeclaration,
+    ): void {
+        if (classNode.heritageClauses === undefined) return;
+
+        for (const heritage of classNode.heritageClauses)
+            for (const hType of heritage.types) {
+                // MUST BE CLASS
+                const expression: ts.Type = checker.getTypeAtLocation(
+                    hType.expression,
+                );
+                const superNode: ts.Declaration =
+                    expression.symbol.getDeclarations()![0];
+
+                if (!ts.isClassDeclaration(superNode)) continue;
+
+                // SPECIFY GENERICS
+                const usages: ReadonlyArray<ts.TypeNode> =
+                    hType.typeArguments || [];
+                const parameters: ReadonlyArray<ts.TypeParameterDeclaration> =
+                    superNode.typeParameters || [];
+
+                parameters.forEach((param, index) => {
+                    const paramType: ts.Type = checker.getTypeAtLocation(param);
+                    const usageType: ts.Type =
+                        usages[index] !== undefined
+                            ? checker.getTypeAtLocation(usages[index])
+                            : checker.getTypeAtLocation(param.default!);
+
+                    dict.set(paramType, usageType);
+                });
+
+                // RECUSRIVE EXPLORATION
+                explore(checker, dict, superNode);
+            }
+    }
+}

package/src/analyses/ImportAnalyzer.ts

@@ -0,0 +1,143 @@
+import { HashMap } from "tstl/container/HashMap";
+import { HashSet } from "tstl/container/HashSet";
+import ts from "typescript";
+
+import { ITypeTuple } from "../structures/ITypeTuple";
+import { GenericAnalyzer } from "./GenericAnalyzer";
+
+export namespace ImportAnalyzer {
+    export interface IOutput {
+        features: [string, string[]][];
+        alias: string;
+    }
+
+    export type Dictionary = HashMap<string, HashSet<string>>;
+
+    export function analyze(
+        checker: ts.TypeChecker,
+        genericDict: GenericAnalyzer.Dictionary,
+        importDict: Dictionary,
+        type: ts.Type,
+    ): ITypeTuple {
+        type = get_type(checker, type);
+        return {
+            type,
+            name: explore_escaped_name(checker, genericDict, importDict, type),
+        };
+    }
+
+    /* ---------------------------------------------------------
+        TYPE
+    --------------------------------------------------------- */
+    function get_type(checker: ts.TypeChecker, type: ts.Type): ts.Type {
+        const symbol: ts.Symbol | undefined = type.getSymbol();
+        return symbol && get_name(symbol) === "Promise"
+            ? escape_promise(checker, type)
+            : type;
+    }
+
+    function escape_promise(checker: ts.TypeChecker, type: ts.Type): ts.Type {
+        const generic: readonly ts.Type[] = checker.getTypeArguments(
+            type as ts.TypeReference,
+        );
+        if (generic.length !== 1)
+            throw new Error(
+                "Error on ImportAnalyzer.analyze(): invalid promise type.",
+            );
+        return generic[0];
+    }
+
+    function get_name(symbol: ts.Symbol): string {
+        return explore_name(
+            symbol.escapedName.toString(),
+            symbol.getDeclarations()![0].parent,
+        );
+    }
+
+    /* ---------------------------------------------------------
+        ESCAPED TEXT WITH IMPORT STATEMENTS
+    --------------------------------------------------------- */
+    function explore_escaped_name(
+        checker: ts.TypeChecker,
+        genericDict: GenericAnalyzer.Dictionary,
+        importDict: Dictionary,
+        type: ts.Type,
+    ): string {
+        //----
+        // CONDITIONAL BRANCHES
+        //----
+        // DECOMPOSE GENERIC ARGUMENT
+        while (genericDict.has(type) === true) type = genericDict.get(type)!;
+
+        // PRIMITIVE
+        const symbol: ts.Symbol | undefined =
+            type.aliasSymbol || type.getSymbol();
+        if (symbol === undefined)
+            return checker.typeToString(type, undefined, undefined);
+        // UNION OR INTERSECT
+        else if (
+            type.aliasSymbol === undefined &&
+            type.isUnionOrIntersection()
+        ) {
+            const joiner: string = type.isIntersection() ? " & " : " | ";
+            return type.types
+                .map((child) =>
+                    explore_escaped_name(
+                        checker,
+                        genericDict,
+                        importDict,
+                        child,
+                    ),
+                )
+                .join(joiner);
+        }
+
+        //----
+        // SPECIALIZATION
+        //----
+        const name: string = get_name(symbol);
+        const sourceFile: ts.SourceFile =
+            symbol.declarations![0].getSourceFile();
+
+        if (sourceFile.fileName.indexOf("typescript/lib") === -1) {
+            const set: HashSet<string> = importDict.take(
+                sourceFile.fileName,
+                () => new HashSet(),
+            );
+            set.insert(name.split(".")[0]);
+        }
+
+        // CHECK GENERIC
+        const generic: readonly ts.Type[] = type.aliasSymbol
+            ? type.aliasTypeArguments || []
+            : checker.getTypeArguments(type as ts.TypeReference);
+        return generic.length
+            ? name === "Promise"
+                ? explore_escaped_name(
+                      checker,
+                      genericDict,
+                      importDict,
+                      generic[0],
+                  )
+                : `${name}<${generic
+                      .map((child) =>
+                          explore_escaped_name(
+                              checker,
+                              genericDict,
+                              importDict,
+                              child,
+                          ),
+                      )
+                      .join(", ")}>`
+            : name;
+    }
+
+    function explore_name(name: string, decl: ts.Node): string {
+        return ts.isModuleBlock(decl)
+            ? explore_name(
+                  `${decl.parent.name.getText()}.${name}`,
+                  decl.parent.parent,
+              )
+            : name;
+    }
+}

package/src/analyses/PathAnalyzer.ts

@@ -0,0 +1,58 @@
+import path from "path";
+import { Token, parse } from "path-to-regexp";
+
+export namespace PathAnalyzer {
+    export const join = (...args: string[]) =>
+        "/" +
+        _Trim(
+            path
+                .join(...args)
+                .split("\\")
+                .join("/"),
+        );
+
+    export const espace = (str: string, method: () => string) =>
+        "/" +
+        _Parse(str, method)
+            .map((arg) => (arg.type === "param" ? `:${arg.value}` : arg.value))
+            .join("/");
+
+    export const parameters = (str: string, method: () => string) =>
+        _Parse(str, method)
+            .filter((arg) => arg.type === "param")
+            .map((arg) => arg.value);
+
+    function _Parse(str: string, method: () => string): IArgument[] {
+        const tokens: Token[] = parse(path.join(str).split("\\").join("/"));
+        const output: IArgument[] = [];
+
+        for (const key of tokens) {
+            if (typeof key === "string")
+                output.push({
+                    type: "path",
+                    value: _Trim(key),
+                });
+            else if (typeof key.name === "number" || _Trim(key.name) === "")
+                throw new Error(`Error on ${method}: ${ERROR_MESSAGE}.`);
+            else
+                output.push({
+                    type: "param",
+                    value: _Trim(key.name),
+                });
+        }
+        return output;
+    }
+
+    function _Trim(str: string): string {
+        if (str[0] === "/") str = str.substring(1);
+        if (str[str.length - 1] === "/") str = str.substring(0, str.length - 1);
+        return str;
+    }
+
+    interface IArgument {
+        type: "param" | "path";
+        value: string;
+    }
+}
+
+const ERROR_MESSAGE = "nestia supports only string typed parameter on path";