@nestia/core 0.1.0

package/src/decorators/TypedParam.ts

@@ -0,0 +1,70 @@
+import {
+    BadRequestException,
+    ExecutionContext,
+    createParamDecorator,
+} from "@nestjs/common";
+import type express from "express";
+
+/**
+ * URL parameter decorator with type.
+ *
+ * `TypedParam` is a decorator function getting specific typed parameter from the HTTP
+ * request URL. It's almost same with the {@link nest.Param}, but `TypedParam` can specify
+ * the parameter type manually. Beside, the {@link nest.Param} always parses all of the
+ * parameters as string type.
+ *
+ * ```typescript
+ * \@TypedRoute.Get("shopping/sales/:section/:id/:paused")
+ * public async pause
+ *     (
+ *         \@TypedParam("section", "string") section: string,
+ *         \@TypedParam("id", "number") id: number,
+ *         \@TypedParam("paused", "boolean", true) paused: boolean | null
+ *     ): Promise<void>;
+ * ```
+ *
+ * @param name URL Parameter name
+ * @param type Type of the URL parameter
+ * @returns Parameter decorator
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export function TypedParam(
+    name: string,
+    type: "boolean" | "number" | "string" | "uuid" = "string",
+    nullable: boolean = false,
+) {
+    return createParamDecorator(function TypedParam(
+        {}: any,
+        ctx: ExecutionContext,
+    ) {
+        const request: express.Request = ctx.switchToHttp().getRequest();
+        const str: string = request.params[name];
+
+        if (nullable === true && str === "null") return null;
+        else if (type === "boolean") {
+            if (str === "true" || str === "1") return true;
+            else if (str === "false" || str === "0") return false;
+            else
+                throw new BadRequestException(
+                    `Value of the URL parameter '${name}' is not a boolean.`,
+                );
+        } else if (type === "number") {
+            const value: number = Number(str);
+            if (isNaN(value))
+                throw new BadRequestException(
+                    `Value of the URL parameter "${name}" is not a number.`,
+                );
+            return value;
+        } else if (type === "uuid") {
+            if (UUID_PATTERN.test(str) === false)
+                throw new BadRequestException(
+                    `Value of the URL parameter "${name}" is not a valid UUID.`,
+                );
+            return str;
+        } else return str;
+    })(name);
+}
+
+const UUID_PATTERN =
+    /^[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$/i;

package/src/decorators/TypedRoute.ts

@@ -0,0 +1,149 @@
+import {
+    CallHandler,
+    Delete,
+    ExecutionContext,
+    Get,
+    NestInterceptor,
+    Patch,
+    Post,
+    Put,
+    UseInterceptors,
+    applyDecorators,
+} from "@nestjs/common";
+import { HttpArgumentsHost } from "@nestjs/common/interfaces";
+import express from "express";
+import { Observable, catchError, map } from "rxjs";
+import {
+    assertStringify,
+    isStringify,
+    stringify,
+    validateStringify,
+} from "typia";
+
+import { IResponseBodyStringifier } from "../options/IResponseBodyStringifier";
+import { get_path_and_stringify } from "./internal/get_path_and_stringify";
+import { route_error } from "./internal/route_error";
+
+/**
+ * Safe router decorator functions.
+ *
+ * `TypedRoute` is a module containing router decorator functions which can boost up
+ * JSON string conversion speed about 5x times faster, through
+ * [`typia.stringify()`](https://github.com/samchon/typia#fastest-json-string-conversion).
+ *
+ * Also, router functions in `TypedRoute` can convert custom error classes to the
+ * regular {@link nest.HttpException} class automatically, through
+ * {@link ExceptionManager}.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ */
+export namespace TypedRoute {
+    /**
+     * Router decorator function for the GET method.
+     *
+     * @param path Path of the HTTP request
+     * @returns Method decorator
+     */
+    export const Get = Generator("Get");
+
+    /**
+     * Router decorator function for the POST method.
+     *
+     * @param path Path of the HTTP request
+     * @returns Method decorator
+     */
+    export const Post = Generator("Post");
+
+    /**
+     * Router decorator function for the PATH method.
+     *
+     * @param path Path of the HTTP request
+     * @returns Method decorator
+     */
+    export const Patch = Generator("Patch");
+
+    /**
+     * Router decorator function for the PUT method.
+     *
+     * @param path Path of the HTTP request
+     * @returns Method decorator
+     */
+    export const Put = Generator("Put");
+
+    /**
+     * Router decorator function for the DELETE method.
+     *
+     * @param path Path of the HTTP request
+     * @returns Method decorator
+     */
+    export const Delete = Generator("Delete");
+
+    /**
+     * @internal
+     */
+    function Generator(method: "Get" | "Post" | "Put" | "Patch" | "Delete") {
+        function route(path?: string | string[]): MethodDecorator;
+        function route<T>(
+            stringify?: IResponseBodyStringifier<T>,
+        ): MethodDecorator;
+        function route<T>(
+            path: string | string[],
+            stringify?: IResponseBodyStringifier<T>,
+        ): MethodDecorator;
+
+        function route(...args: any[]): MethodDecorator {
+            const [path, stringify] = get_path_and_stringify(
+                `TypedRoute.${method}`,
+            )(...args);
+            return applyDecorators(
+                ROUTERS[method](path),
+                UseInterceptors(new TypedRouteInterceptor(stringify)),
+            );
+        }
+        return route;
+    }
+}
+for (const method of [
+    assertStringify,
+    isStringify,
+    stringify,
+    validateStringify,
+]) {
+    Object.assign(TypedRoute.Get, method);
+    Object.assign(TypedRoute.Delete, method);
+    Object.assign(TypedRoute.Post, method);
+    Object.assign(TypedRoute.Put, method);
+    Object.assign(TypedRoute.Patch, method);
+}
+
+/**
+ * @internal
+ */
+class TypedRouteInterceptor implements NestInterceptor {
+    public constructor(private readonly stringify: (input: any) => string) {}
+
+    public intercept(
+        context: ExecutionContext,
+        next: CallHandler,
+    ): Observable<any> {
+        const http: HttpArgumentsHost = context.switchToHttp();
+        const response: express.Response = http.getResponse();
+        response.header("Content-Type", "application/json");
+
+        return next.handle().pipe(
+            map((value) => this.stringify(value)),
+            catchError((err) => route_error(http.getRequest(), err)),
+        );
+    }
+}
+
+/**
+ * @internal
+ */
+const ROUTERS = {
+    Get,
+    Post,
+    Patch,
+    Put,
+    Delete,
+};

package/src/decorators/internal/EncryptedConstant.ts

@@ -0,0 +1,4 @@
+/**
+ * @internal
+ */
+export const ENCRYPTION_METADATA_KEY = "nestia:core:encryption:password";

package/src/decorators/internal/get_path_and_stringify.ts

@@ -0,0 +1,76 @@
+import { InternalServerErrorException } from "@nestjs/common";
+import { IValidation, TypeGuardError } from "typia";
+
+import { IResponseBodyStringifier } from "../../options/IResponseBodyStringifier";
+
+export const get_path_and_stringify =
+    (method: string) =>
+    (
+        ...args: any[]
+    ): [string | string[] | undefined, (input: any) => string] => {
+        const path: string | string[] | null | undefined =
+            args[0] === undefined ||
+            typeof args[0] === "string" ||
+            Array.isArray(args[0])
+                ? args[0]
+                : null;
+        const functor: IResponseBodyStringifier<any> | undefined =
+            path === null ? args[0] : args[1];
+        return [path ?? undefined, take(method)(functor)];
+    };
+
+const take =
+    (method: string) =>
+    <T>(functor?: IResponseBodyStringifier<T>) => {
+        if (functor === undefined)
+            throw new Error(
+                `Error on nestia.core.${method}(): no stringify function provided.`,
+            );
+        else if (functor.type === "stringify") return functor.stringify;
+        else if (functor.type === "assert") return assert(functor.assert);
+        else if (functor.type === "is") return is(functor.is);
+        else if (functor.type === "validate") return validate(functor.validate);
+        throw new Error(
+            `Error on nestia.core.${method}(): invalid typed stringify function.`,
+        );
+    };
+
+const assert =
+    <T>(closure: (data: T) => string) =>
+    (data: T) => {
+        try {
+            return closure(data);
+        } catch (exp) {
+            if (exp instanceof TypeGuardError) {
+                throw new InternalServerErrorException({
+                    path: exp.path,
+                    reason: exp.message,
+                    expected: exp.expected,
+                    message: MESSAGE,
+                });
+            }
+            throw exp;
+        }
+    };
+
+const is =
+    <T>(closure: (data: T) => string | null) =>
+    (data: T) => {
+        const result: string | null = closure(data);
+        if (result === null) throw new InternalServerErrorException(MESSAGE);
+        return result;
+    };
+
+const validate =
+    <T>(closure: (data: T) => IValidation<string>) =>
+    (data: T) => {
+        const result: IValidation<string> = closure(data);
+        if (result.success === false)
+            throw new InternalServerErrorException({
+                errors: result.errors,
+                message: MESSAGE,
+            });
+        return result.data;
+    };
+
+const MESSAGE = "Response body data is not following the promised type.";

package/src/decorators/internal/headers_to_object.ts

@@ -0,0 +1,13 @@
+import http from "http";
+
+/**
+ * @internal
+ */
+export function headers_to_object(
+    headers: http.IncomingHttpHeaders,
+): Record<string, string> {
+    const output: Record<string, string> = {};
+    for (const [key, value] of Object.entries(headers))
+        output[key] = value instanceof Array ? value[0] : value || "";
+    return output;
+}

package/src/decorators/internal/route_error.ts

@@ -0,0 +1,41 @@
+import { HttpException } from "@nestjs/common";
+import express from "express";
+import { Observable, throwError } from "rxjs";
+
+import { ExceptionManager } from "../../utils/ExceptionManager";
+
+/**
+ * @internal
+ */
+export function route_error(
+    request: express.Request,
+    error: any,
+): Observable<never> {
+    error = (() => {
+        // HTTP-ERROR
+        if (error instanceof HttpException) return error;
+
+        // CUSTOM-REGISTERED ERROR
+        for (const [creator, closure] of ExceptionManager.tuples)
+            if (error instanceof creator) return closure(error);
+
+        // MAYBE INTERNAL ERROR
+        return error;
+    })();
+
+    try {
+        error.method = request.method;
+        error.path = request.path;
+    } catch {}
+
+    setTimeout(() => {
+        for (const listener of ExceptionManager.listeners) {
+            try {
+                const res: any | Promise<any> = listener(error);
+                if (typeof res === "object" && typeof res.catch === "function")
+                    res.catch(() => {});
+            } catch {}
+        }
+    }, 0);
+    return throwError(() => error);
+}

package/src/decorators/internal/validate_request_body.ts

@@ -0,0 +1,58 @@
+import { BadRequestException } from "@nestjs/common";
+import { IValidation, TypeGuardError } from "typia";
+
+import { IRequestBodyValidator } from "../../options/IRequestBodyValidator";
+
+export const validate_request_body =
+    (method: string) =>
+    <T>(validator?: IRequestBodyValidator<T>) => {
+        if (!validator)
+            throw new Error(
+                `Error on nestia.core.${method}(): no transformer.`,
+            );
+        else if (validator.type === "assert") return assert(validator.assert);
+        else if (validator.type === "is") return is(validator.is);
+        else if (validator.type === "validate")
+            return validate(validator.validate);
+        throw new Error(
+            `Error on nestia.core.${method}(): invalid typed validator.`,
+        );
+    };
+
+const assert =
+    <T>(closure: (data: T) => T) =>
+    (data: T) => {
+        try {
+            closure(data);
+        } catch (exp) {
+            if (exp instanceof TypeGuardError) {
+                throw new BadRequestException({
+                    path: exp.path,
+                    reason: exp.message,
+                    expected: exp.expected,
+                    message: MESSAGE,
+                });
+            }
+            throw exp;
+        }
+    };
+
+const is =
+    <T>(closure: (data: T) => boolean) =>
+    (data: T) => {
+        const success: boolean = closure(data);
+        if (success === false) throw new BadRequestException(MESSAGE);
+    };
+
+const validate =
+    <T>(closure: (data: T) => IValidation<T>) =>
+    (data: T) => {
+        const result: IValidation<T> = closure(data);
+        if (result.success === false)
+            throw new BadRequestException({
+                errors: result.errors,
+                message: MESSAGE,
+            });
+    };
+
+const MESSAGE = "Request body data is not following the promised type.";

package/src/index.ts

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

package/src/module.ts

@@ -0,0 +1,9 @@
+export * from "./decorators/EncryptedBody";
+export * from "./decorators/EncryptedController";
+export * from "./decorators/EncryptedModule";
+export * from "./decorators/EncryptedRoute";
+export * from "./utils/ExceptionManager";
+export * from "./decorators/PlainBody";
+export * from "./decorators/TypedBody";
+export * from "./decorators/TypedParam";
+export * from "./decorators/TypedRoute";

package/src/options/INestiaTransformOptions.ts

@@ -0,0 +1,6 @@
+import { ITransformOptions } from "typia/lib/transformers/ITransformOptions";
+
+export interface INestiaTransformOptions extends ITransformOptions {
+    validate?: "assert" | "is" | "validate";
+    stringify?: "stringify" | "assert" | "is" | "validate";
+}

package/src/options/INestiaTransformProject.ts

@@ -0,0 +1,6 @@
+import { IProject } from "typia/lib/transformers/IProject";
+import { INestiaTransformOptions } from "./INestiaTransformOptions";
+
+export interface INestiaTransformProject extends Omit<IProject, "options"> {
+    options: INestiaTransformOptions;
+}

package/src/options/IRequestBodyValidator.ts

@@ -0,0 +1,20 @@
+import { IValidation } from "typia";
+
+export type IRequestBodyValidator<T> =
+    | IRequestBodyValidator.IAssert<T>
+    | IRequestBodyValidator.IIs<T>
+    | IRequestBodyValidator.IValidate<T>;
+export namespace IRequestBodyValidator {
+    export interface IAssert<T> {
+        type: "assert";
+        assert: (input: T) => T;
+    }
+    export interface IIs<T> {
+        type: "is";
+        is: (input: T) => boolean;
+    }
+    export interface IValidate<T> {
+        type: "validate";
+        validate: (input: T) => IValidation<T>;
+    }
+}

package/src/options/IResponseBodyStringifier.ts

@@ -0,0 +1,25 @@
+import { IValidation } from "typia";
+
+export type IResponseBodyStringifier<T> =
+    | IResponseBodyStringifier.IStringify<T>
+    | IResponseBodyStringifier.IIs<T>
+    | IResponseBodyStringifier.IAssert<T>
+    | IResponseBodyStringifier.IValidate<T>;
+export namespace IResponseBodyStringifier {
+    export interface IStringify<T> {
+        type: "stringify";
+        stringify: (input: T) => string;
+    }
+    export interface IIs<T> {
+        type: "is";
+        is: (input: T) => string | null;
+    }
+    export interface IAssert<T> {
+        type: "assert";
+        assert: (input: T) => string;
+    }
+    export interface IValidate<T> {
+        type: "validate";
+        validate: (input: T) => IValidation<string>;
+    }
+}

package/src/transform.ts

@@ -0,0 +1,20 @@
+import ts from "typescript";
+import { IProject } from "typia/lib/transformers/IProject";
+
+import { INestiaTransformOptions } from "./options/INestiaTransformOptions";
+import { FileTransformer } from "./transformers/FileTransformer";
+
+export default function transform(
+    program: ts.Program,
+    options?: INestiaTransformOptions,
+): ts.TransformerFactory<ts.SourceFile> {
+    const project: IProject = {
+        program,
+        compilerOptions: program.getCompilerOptions(),
+        checker: program.getTypeChecker(),
+        printer: ts.createPrinter(),
+        options: options || {},
+    };
+    return (context) => (file) =>
+        FileTransformer.transform(project, context, file);
+}

package/src/transformers/BodyTransformer.ts

@@ -0,0 +1,106 @@
+import path from "path";
+import ts from "typescript";
+import { AssertProgrammer } from "typia/lib/programmers/AssertProgrammer";
+import { IsProgrammer } from "typia/lib/programmers/IsProgrammer";
+import { ValidateProgrammer } from "typia/lib/programmers/ValidateProgrammer";
+import { IProject } from "typia/lib/transformers/IProject";
+
+import { INestiaTransformProject } from "../options/INestiaTransformProject";
+
+export namespace BodyTransformer {
+    export function transform(
+        project: INestiaTransformProject,
+        type: ts.Type,
+        decorator: ts.Decorator,
+    ): ts.Decorator {
+        if (!ts.isCallExpression(decorator.expression)) return decorator;
+        return ts.factory.createDecorator(
+            validate(project, type, decorator.expression),
+        );
+    }
+
+    function validate(
+        project: INestiaTransformProject,
+        type: ts.Type,
+        expression: ts.CallExpression,
+    ): ts.LeftHandSideExpression {
+        // CHECK SIGNATURE
+        const signature: ts.Signature | undefined =
+            project.checker.getResolvedSignature(expression);
+        if (!signature || !signature.declaration) return expression;
+
+        // CHECK TO BE TRANSFORMED
+        const validate: boolean = (() => {
+            // CHECK FILENAME
+            const location: string = path.resolve(
+                signature.declaration.getSourceFile().fileName,
+            );
+            if (
+                LIB_PATHS.every((str) => location.indexOf(str) === -1) &&
+                SRC_PATHS.every((str) => location !== str)
+            )
+                return false;
+
+            // CHECK DUPLICATED TRANSFORMATION
+            return expression.arguments.length === 0;
+        })();
+        if (validate === false) return expression;
+
+        // CHECK TYPE NODE
+        const typeNode: ts.TypeNode | undefined =
+            project.checker.typeToTypeNode(type, undefined, undefined);
+        if (typeNode === undefined) return expression;
+
+        //----
+        // TRANSFORMATION
+        //----
+        // GENERATE VALIDATION PLAN
+        const parameter = (
+            key: string,
+            programmer: (
+                project: IProject,
+                modulo: ts.LeftHandSideExpression,
+            ) => (type: ts.Type) => ts.ArrowFunction,
+        ) =>
+            ts.factory.createObjectLiteralExpression([
+                ts.factory.createPropertyAssignment(
+                    ts.factory.createIdentifier("type"),
+                    ts.factory.createStringLiteral(key),
+                ),
+                ts.factory.createPropertyAssignment(
+                    ts.factory.createIdentifier(key),
+                    programmer(project, expression.expression)(type),
+                ),
+            ]);
+        const validator: ts.ObjectLiteralExpression = (() => {
+            if (project.options.validate === "is")
+                return parameter("is", IsProgrammer.generate);
+            else if (project.options.validate === "validate")
+                return parameter("validate", ValidateProgrammer.generate);
+            return parameter("assert", AssertProgrammer.generate);
+        })();
+
+        // UPDATE DECORATOR FUNCTION CALL
+        return ts.factory.updateCallExpression(
+            expression,
+            expression.expression,
+            expression.typeArguments,
+            [validator],
+        );
+    }
+
+    const CLASSES = ["EncryptedBody", "TypedBody"];
+    const LIB_PATHS = CLASSES.map((cla) =>
+        path.join(
+            "node_modules",
+            "@nestia",
+            "core",
+            "lib",
+            "decorators",
+            `${cla}.d.ts`,
+        ),
+    );
+    const SRC_PATHS = CLASSES.map((cla) =>
+        path.resolve(path.join(__dirname, "..", "decorators", `${cla}.ts`)),
+    );
+}

package/src/transformers/FileTransformer.ts

@@ -0,0 +1,49 @@
+import ts from "typescript";
+
+import { INestiaTransformProject } from "../options/INestiaTransformProject";
+import { NodeTransformer } from "./NodeTransformer";
+
+export namespace FileTransformer {
+    export function transform(
+        project: INestiaTransformProject,
+        context: ts.TransformationContext,
+        file: ts.SourceFile,
+    ): ts.SourceFile {
+        // ITERATE NODES
+        return ts.visitEachChild(
+            file,
+            (node) => iterate_node(project, context, node),
+            context,
+        );
+    }
+
+    function iterate_node(
+        project: INestiaTransformProject,
+        context: ts.TransformationContext,
+        node: ts.Node,
+    ): ts.Node {
+        return ts.visitEachChild(
+            try_transform_node(project, node),
+            (child) => iterate_node(project, context, child),
+            context,
+        );
+    }
+
+    function try_transform_node(
+        project: INestiaTransformProject,
+        node: ts.Node,
+    ): ts.Node {
+        try {
+            return NodeTransformer.transform(project, node);
+        } catch (exp) {
+            if (!(exp instanceof Error)) throw exp;
+
+            const file: ts.SourceFile = node.getSourceFile();
+            const { line, character } = file.getLineAndCharacterOfPosition(
+                node.pos,
+            );
+            exp.message += ` - ${file.fileName}.${line + 1}:${character + 1}`;
+            throw exp;
+        }
+    }
+}