nestia 0.2.2 → 0.3.1

package/README.md

@@ -6,21 +6,42 @@ Automatic SDK generator for the NestJS.
 [![Downloads](https://img.shields.io/npm/dm/nestia.svg)](https://www.npmjs.com/package/nestia)
 [![Build Status](https://github.com/samchon/nestia/workflows/build/badge.svg)](https://github.com/samchon/nestia/actions?query=workflow%3Abuild)
 
-## Outline
-If you're making a backend server with the **TypeScript** and **NestJS**, you don't need any extra dedication, for delivering Rest API to the client (front-end) developers, like writing `swagger.json` comments.
-
-Just generate a SDK library through the **Nestia** and deliver the SDK library to the client developers. The client developers can call your backend server API just by calling the SDK library functions with *await* symbol, re-using the interfaces what you've defined.
-
 ```bash
 npm install --save-dev nestia
 npx nestia sdk "src/controller" --out "src/api"
 ```
 
-If you want to see an example project using the **Nestia**, click below links:
+Don't write any `swagger` comment. Just deliver the SDK.
+
+When you're developing a backend server using the `NestJS`, you don't need any extra dedication, for delivering the Rest API to the client developers, like writing the `swagger` comments. You just run this **Nestia** up, then **Nestia** would generate the SDK automatically, by analyzing your controller classes in the compliation and runtime level.
+
+With the automatically generated SDK through this **Nestia**, client developer also does not need any extra work, like reading `swagger` and writing the duplicated interaction code. Client developer only needs to import the SDK and calls matched function with the `await` symbol.
 
-  - [Controllers of the NestJS](https://github.surf/samchon/nestia/blob/HEAD/src/test/controllers/base/SaleCommentsController.ts)
-  - [Structures used in the RestAPI](https://github.surf/samchon/nestia/blob/HEAD/api/structures/sales/articles/ISaleArticle.ts)
-  - [**SDK generated by the Nestia**](https://github.surf/samchon/nestia/blob/HEAD/api/functional/consumers/sales/reviews/index.ts)
+```typescript
+import api from "@samchon/bbs-api";
+import { IBbsArticle } from "@samchon/bbs-api/lib/structures/bbs/IBbsArticle";
+import { IPage } from "@samchon/bbs-api/lib/structures/common/IPage";
+
+export async function test_article_read(connection: api.IConnection): Promise<void>
+{
+    // LIST UP ARTICLE SUMMARIES
+    const index: IPage<IBbsArticle.ISummary> = await api.functional.bbs.articles.index
+    (
+        connection,
+        "free",
+        { limit: 100, page: 1 }
+    );
+
+    // READ AN ARTICLE DETAILY
+    const article: IBbsArticle = await api.functional.bbs.articles.at
+    (
+        connection,
+        "free",
+        index.data[0].id
+    );
+    console.log(article.title, aritlce.body, article.files);
+}
+```
 
 
 
@@ -29,29 +50,215 @@ If you want to see an example project using the **Nestia**, click below links:
 ### Installation
 ```bash
 npm install --save-dev nestia
-npx nestia sdk "src/controllers" --out "src/api"
 ```
 
 Installing the **Nestia** is very easy.
 
 Just type the `npm install --save-dev nestia` command in your NestJS backend project.
 
-### CLI options
+### SDK generation
 ```bash
 npx nestia sdk <source_controller_directory> --out <output_sdk_directory>
 
 npx nestia sdk "src/controllers" --out "src/api"
-npx nestia sdk "src/consumers/controllers" "src/sellers/controllers" --out "src/api
+npx nestia sdk "src/controllers/consumers" "src/controllers/sellers" --out "src/api
 ```
 
-To generate a SDK library through the **Nestia** is very easy. Just type the `nestia sdk <input> --out <output>` command in the console. If there're multiple source directories containing the NestJS controller classes, type all of them separating by a `space` word.
+To generate a SDK library through the **Nestia** is very easy. 
+
+Just type the `nestia sdk <input> --out <output>` command in the console. If there're multiple source directories containing the NestJS controller classes, type all of them separating by a `space` word.
 
+Also, when generating a SDK using the cli options, `compilerOptions` would follow the `tsconfig.json`, that is configured for the backend server. If no `tsconfig.json` file exists in your project, the configuration would be default option (`ES5` with `strict` mode). If you want to use different `compilerOptions` with the `tsconfig.json`, you should configure the [nestia.config.ts](#nestiaconfigts).
 
 ```bash
 npx nestia install
 ```
 
-Also, SDK library generated by the **Nestia** has some dependencies like below. When you type the `nestia install` command in the console, those dependencies would be automatically install and would be enrolled to the `dependencies` field in the `package.json`
+### Dependencies
+SDK library generated by the **Nestia** has some dependencies like below. 
+
+When you type the `nestia install` command in the console, those dependencies would be automatically installed and enrolled to the `dependencies` and `devDependencies` fields in the `package.json`
 
   - [@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/node)
-  - [node-fetch](https://github.com/node-fetch/node-fetch)
+  - [node-fetch](https://github.com/node-fetch/node-fetch)
+
+
+
+
+## Advanced
+### `nestia.config.ts`
+```typescript
+export namespace NestiaApplication
+{
+    export interface IConfiguration
+    {
+        /**
+         * List of directories containing the NestJS controller classes.
+         */
+        input: string | string[];
+
+        /**
+         * Output directory that SDK would be placed in.
+         */
+        output: string;
+
+        /**
+         * Compiler options for the TypeScript.
+         * 
+         * If omitted, the configuration would follow the `tsconfig.json`.
+         */
+        compilerOptions?: tsc.CompilerOptions
+    }
+}
+```
+
+Instead of specifying `input` and `output` directories using the cli options, you can specify those directories as an independent configuration file. It's the `nestia.config.ts` and with the `nestia.config.ts` file, you also configure independent TypeScript compiler option from the `tsconfig.json`.
+
+Write below content as the `nestia.config.ts` file and place it onto the root directory of your backend project. After the configuration, you can generate the SDK only with the `npx nestia sdk` command, without any directory specification. 
+
+```typescript
+export = {
+    input: "src/controllers`",
+    output: "src/api"
+};
+```
+
+
+
+### Recommended Structures
+When developing a NestJS backend server with this **Nestia**, I recommend you to follow below directory structure. The key princinple of below structure is to gathering all of the DTO interface structures into the `src/api/structures` directory and gather all of the controller classes into the `src/controllers` directory.
+
+If you place the SDK onto the `src/api` directory and gather all of the DTO interface structures into the `src/api/structures` directory, you can publish the SDK library very easily without any special configuration. Also when you're develop the test automation program, you can implement the API testing features very convenienty through the automatically generated SDK through this **Nestia**.
+
+  - src
+    - api
+      - **functional**: automatically generated SDK functions
+      - **structures**: DTO structures
+    - controllers
+    - providers
+    - models
+    - **test**: Test automation program using SDK functions
+  - package.json
+  - tsconfig.json
+  - nestia.config.ts
+
+For your deep understanding about this directory structure with this **Nestia**, I've prepared an example backend project. Looking around the example repository and reading the [README.md](https://github.com/samchon/backend#13-directories) of it, you can feel that such directory structure is how convenient for SDK publishing and test automation program implementation.
+
+  - https://github.com/samchon/backend
+
+
+
+
+## Demonstration
+To demonstrate which SDK codes would be generated by this **Nestia**:
+
+  - [Controllers of the NestJS](https://github.surf/samchon/nestia/blob/HEAD/test/default/src/controllers/base/SaleCommentsController.ts)
+  - [Structures used in the RestAPI](https://github.surf/samchon/nestia/blob/HEAD/test/default/src/api/structures/sales/articles/ISaleArticle.ts)
+  - [SDK generated by this **Nestia**](https://github.surf/samchon/nestia/blob/HEAD/test/default/src/api/functional/consumers/sales/reviews/index.ts)
+
+### Controller
+If you've decided to adapt this **Nestia** and you want to generate the SDK directly, you don't need any extra work. Just keep you controller class down and do noting. The only one exceptional case that you need an extra dedication is, when you want to explain about the API function to the client developers through the comments.
+
+```typescript
+@nest.Controller("consumers/:section/sales/:saleId/questions")
+export class ConsumerSaleQuestionsController
+{
+    /**
+     * Store a new question.
+     * 
+     * @param request Instance of the Express.Request
+     * @param section Code of the target section
+     * @param saleId ID of the target sale
+     * @param input Content to archive
+     * 
+     * @return Newly archived question
+     * @throw 400 bad request error when type of the input data is not valid
+     * @throw 401 unauthorized error when you've not logged in yet
+     */
+    @nest.Post()
+    public store
+        (
+            @nest.Request() request: express.Request,
+            @nest.Param("section") section: string, 
+            @nest.Param("saleId") saleId: number, 
+            @nest.Body() input: ISaleQuestion.IStore
+        ): Promise<ISaleQuestion>;
+}
+```
+
+### SDK
+When you run the **Nestia** up using the upper controller class `ConsumerSaleQuestionsController`, the **Nestia** would generate below function for the client developers, by analyzing the `ConsumerSaleQuestionsController` class in the compilation and runtime level.
+
+As you can see, the comments from the `ConsumerSaleQuestionsController.store()` are fully copied to the SDK function. Therefore, if you want to deliver detailed description about the API function, writing the detailed comment would be tne best choice.
+
+```typescript
+/**
+ * Store a new question.
+ * 
+ * @param connection connection Information of the remote HTTP(s) server with headers (+encryption password)
+ * @param request Instance of the Express.Request
+ * @param section Code of the target section
+ * @param saleId ID of the target sale
+ * @param input Content to archive
+ * @return Newly archived question
+ * @throw 400 bad request error when type of the input data is not valid
+ * @throw 401 unauthorized error when you've not logged in yet
+ * 
+ * @nestia Generated by Nestia - https://github.com/samchon/nestia
+ * @controller ConsumerSaleQuestionsController.store()
+ * @path POST /consumers/:section/sales/:saleId/questions/
+ */
+export function store
+    (
+        connection: IConnection,
+        section: string,
+        saleId: number,
+        input: store.Input
+    ): Promise<store.Output>
+{
+    return Fetcher.fetch
+    (
+        connection,
+        {
+            input_encrypted: false,
+            output_encrypted: false
+        },
+        "POST",
+        `/consumers/${section}/sales/${saleId}/questions/`,
+        input
+    );
+}
+export namespace store
+{
+    export type Input = Primitive<ISaleInquiry.IStore>;
+    export type Output = Primitive<ISaleInquiry<ISaleArticle.IContent>>;
+}
+```
+
+
+
+
+## Appendix
+### Safe-TypeORM
+https://github.com/samchon/safe-typeorm
+
+[safe-typeorm](https://github.com/samchon/safe-typeorm) is another library that what I've developed, helping typeorm in the compilation level and optimizes DB performance automatically without any extra dedication.
+
+Therefore, this **Nestia** makes you to be much convenient in the API interaction level and safe-typeorm helps you to be much convenient in the DB interaction level. With those **Nestia** and [safe-typeorm](https://github.com/samchon/safe-typeorm), let's implement the backend server much easily and conveniently.
+
+### Technial Support
+samchon.github@gmail.com
+
+I can provide technical support about those **Nestia** and [safe-typeorm](https://github.com/samchon/safe-typeorm). 
+
+Therefore, if you have any question or need help, feel free to contact me. If you want to adapt those **Nestia** and [safe-typeorm](https://github.com/samchon/safe-typeorm) in your commercial project, I can provide you the best guidance. 
+
+I also can help your backend project in the entire development level. If you're suffering by DB architecture design or API structure design, just contact me and get help. I'll help you with my best effort.
+
+### Archidraw
+https://www.archisketch.com/
+
+I have special thanks to the Archidraw, where I'm working for.
+
+The Archidraw is a great IT company developing 3D interior editor and lots of solutions based on the 3D assets. Also, the Archidraw is the first company who had adopted this **Nestia** on their commercial backend project, even this **Nestia** was in the alpha level.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestia",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Automatic SDK and Document generator for the NestJS",
   "main": "src/index.ts",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "dev": "tsc --watch",
-    "test": "ts-node src/bin/nestia sdk src/test/controllers --out api"
+    "test": "cd test && bash script.sh"
   },
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "cli": "^1.0.1",
     "del": "^6.0.0",
     "ts-node": "^9.1.1",
-    "tstl": "^2.4.21",
+    "tstl": "^2.5.0",
     "ttypescript": "^1.5.12",
     "typescript": "^4.3.2"
   },

package/src/NestiaApplication.ts

@@ -15,26 +15,18 @@ import { ArrayUtil } from "./utils/ArrayUtil";
 
 export class NestiaApplication
 {
-    public readonly inputs: string[];
-    public readonly output: string;
+    private readonly config_: NestiaApplication.IConfiguration;
+    private readonly bundle_checker_: Singleton<Promise<(str: string) => boolean>>;
 
-    private readonly bundle_checker_: Singleton<(str: string) => boolean>;
-
-    public constructor
-        (
-            inputs: string[], 
-            output: string
-        )
+    public constructor(config: NestiaApplication.IConfiguration)
     {
-        this.inputs = inputs.map(str => path.resolve(str));
-        this.output = path.resolve(output);
-
+        this.config_ = config;
         this.bundle_checker_ = new Singleton(async () =>
         {
             const bundles: string[] = await fs.promises.readdir(`${__dirname}${path.sep}bundle`);
             const tuples: Pair<string, boolean>[] = await ArrayUtil.asyncMap(bundles, async file =>
             {
-                const relative: string = `${this.output}${path.sep}${file}`;
+                const relative: string = `${this.config_.output}${path.sep}${file}`;
                 const stats: fs.Stats = await fs.promises.stat(`${__dirname}${path.sep}bundle${path.sep}${file}`);
 
                 return new Pair(relative, stats.isDirectory());
@@ -52,13 +44,17 @@ export class NestiaApplication
         });
     }
 
-    public async sdk(): Promise<void>
+    public async generate(): Promise<void>
     {
         // LOAD CONTROLLER FILES
         const fileList: string[] = [];
-        for (const input of this.inputs)
+        const inputList: string[] = this.config_.input instanceof Array
+            ? this.config_.input
+            : [this.config_.input];
+
+        for (const file of inputList.map(str => path.resolve(str)))
         {
-            const found: string[] = await SourceFinder.find(input);
+            const found: string[] = await SourceFinder.find(file);
             const filtered: string[] = await ArrayUtil.asyncFilter(found, file => this.is_not_excluded(file));
 
             fileList.push(...filtered);
@@ -72,7 +68,11 @@ export class NestiaApplication
             controllerList.push(...await ReflectAnalyzer.analyze(unique, file));
 
         // ANALYZE TYPESCRIPT CODE
-        const program: tsc.Program = tsc.createProgram(controllerList.map(c => c.file), {});
+        const program: tsc.Program = tsc.createProgram
+        (
+            controllerList.map(c => c.file), 
+            this.config_.compilerOptions || {}
+        );
         const checker: tsc.TypeChecker = program.getTypeChecker();
 
         const routeList: IRoute[] = [];
@@ -86,12 +86,22 @@ export class NestiaApplication
         }
 
         // DO GENERATE
-        await SdkGenerator.generate(this.output, routeList);
+        await SdkGenerator.generate(this.config_.output, routeList);
     }
 
     private async is_not_excluded(file: string): Promise<boolean>
     {
-        return file.indexOf(`${this.output}${path.sep}functional`) === -1
+        return file.indexOf(`${this.config_.output}${path.sep}functional`) === -1
             && (await this.bundle_checker_.get())(file) === false;
     }
 }
+
+export namespace NestiaApplication
+{
+    export interface IConfiguration
+    {
+        input: string | string[];
+        output: string;
+        compilerOptions?: tsc.CompilerOptions;
+    }
+}

package/src/bin/nestia.ts

@@ -3,42 +3,77 @@
 import cli from "cli";
 import fs from "fs";
 import path from "path";
-
-import { Terminal } from "../utils/Terminal";
+import tsc from "typescript";
 
 import { NestiaApplication } from "../NestiaApplication";
 
+import { Terminal } from "../utils/Terminal";
+import { stripJsonComments } from "../utils/stripJsonComments";
+
 interface ICommand
 {
-    install: boolean;
     out: string | null;
 }
 
-async function sdk(inputList: string[], command: ICommand): Promise<void>
+async function sdk(input: string[], command: ICommand): Promise<void>
 {
-    // VALIDATE OUTPUT
+    let compilerOptions: tsc.CompilerOptions | undefined = {};
+
+    //----
+    // NESTIA.CONFIG.TS
+    //----
+    if (fs.existsSync("nestia.config.ts") === true)
+    {
+        const config: NestiaApplication.IConfiguration = await import(path.resolve("nestia.config.ts"));
+        compilerOptions = config.compilerOptions;
+        input = config.input instanceof Array ? config.input : [config.input];
+        command.out = config.output;
+    }
+    
+    //----
+    // VALIDATIONS
+    //----
+    // CHECK OUTPUT
     if (command.out === null)
         throw new Error(`Output directory is not specified. Add the "--out <output_directory>" option.`);
 
+    // CHECK PARENT DIRECTORY
     const parentPath: string = path.resolve(command.out + "/..");
     const parentStats: fs.Stats = await fs.promises.stat(parentPath);
+
     if (parentStats.isDirectory() === false)
         throw new Error(`Unable to find parent directory of the output path: "${parentPath}".`);
 
-    // VALIDATE INPUTS
-    for (const input of inputList)
+    // CHECK INPUTS
+    for (const path of input)
     {
-        const inputStats: fs.Stats = await fs.promises.stat(input);
+        const inputStats: fs.Stats = await fs.promises.stat(path);
         if (inputStats.isDirectory() === false)
-            throw new Error(`Target "${inputList}" is not a directory.`);
+            throw new Error(`Target "${path}" is not a directory.`);
     }
 
     //----
-    // GENERATE
+    // GENERATION
     //----
-    // CALL THE APP.SDK()
-    const app: NestiaApplication = new NestiaApplication(inputList, command.out);
-    await app.sdk();
+    if (fs.existsSync("tsconfig.json") === true)
+    {
+        const content: string = await fs.promises.readFile("tsconfig.json", "utf8");
+        const options: tsc.CompilerOptions = JSON.parse(stripJsonComments(content)).compilerOptions;
+
+        compilerOptions = compilerOptions
+            ? { ...options, ...compilerOptions }
+            : options;
+    }
+
+    // CHECK NESTIA.CONFIG.TS
+
+    // CALL THE APP.GENERATE()
+    const app: NestiaApplication = new NestiaApplication({
+        output: command.out,
+        input,
+        compilerOptions,
+    });
+    await app.generate();
 }
 
 async function install(): Promise<void>
@@ -58,7 +93,6 @@ async function main(): Promise<void>
     {
         const command: ICommand = cli.parse({
             out: ["o", "Output path of the SDK files", "string", null],
-            install: ["i", "Install Dependencies", "boolean", false]
         });
 
         try

package/src/generates/FileGenerator.ts

@@ -34,7 +34,10 @@ export namespace FileGenerator
     function emplace(directory: Directory, route: IRoute): void
     {
         // SEPARATE IDENTIFIERS
-        const identifiers: string[] = route.path.split("/").filter(str => str[0] !== ":" && str.length !== 0);
+        const identifiers: string[] = route.path
+            .split("/")
+            .filter(str => str[0] !== ":" && str.length !== 0)
+            .map(str => str.split("-").join("_").split(".").join("_"));
 
         for (const key of identifiers)
         {

package/src/generates/FunctionGenerator.ts

@@ -14,6 +14,7 @@ export namespace FunctionGenerator
 
         return [head, body, tail]
             .map(closure => closure(route, query, input))
+            .filter(str => !!str)
             .join("\n");
     }
 
@@ -43,11 +44,12 @@ export namespace FunctionGenerator
             fetchArguments.push("input");
 
         // RETURNS WITH FINALIZATION
-        return ""
+        return "{\n"
             + "    return Fetcher.fetch\n"
             + "    (\n"
             + fetchArguments.map(param => `        ${param}`).join(",\n") + "\n"
-            + "    );";
+            + "    );\n"
+            + "}";
     }
 
     function get_path(route: IRoute, query: IRoute.IParameter | undefined): string
@@ -142,11 +144,10 @@ export namespace FunctionGenerator
             + `export function ${route.name}\n` 
             + `    (\n` 
             + `${parameters.map(str => `        ${str}`).join(",\n")}\n`
-            + `    ): Promise<${output}>\n`
-            + "{";
+            + `    ): Promise<${output}>`;
     }
 
-    function tail(route: IRoute, query: IRoute.IParameter | undefined, input: IRoute.IParameter | undefined): string
+    function tail(route: IRoute, query: IRoute.IParameter | undefined, input: IRoute.IParameter | undefined): string | null
     {
         const types: Pair<string, string>[] = [];
         if (query !== undefined)
@@ -157,10 +158,9 @@ export namespace FunctionGenerator
             types.push(new Pair("Output", route.output));
         
         if (types.length === 0)
-            return "}";
+            return null;
         
-        return `}\n`
-            + `export namespace ${route.name}\n`
+        return `export namespace ${route.name}\n`
             + "{\n"
             + (types.map(tuple => `    export type ${tuple.first} = Primitive<${tuple.second}>;`).join("\n")) + "\n"
             + "}";

package/src/utils/stripJsonComments.ts

@@ -0,0 +1,79 @@
+// https://github.com/sindresorhus/strip-json-comments
+
+const singleComment: any = Symbol('singleComment');
+const multiComment: any = Symbol('multiComment');
+
+const stripWithoutWhitespace = () => '';
+const stripWithWhitespace = (string: string, start: number, end: number) => string.slice(start, end).replace(/\S/g, ' ');
+
+const isEscaped = (jsonString: string, quotePosition: number) => {
+    let index = quotePosition - 1;
+    let backslashCount = 0;
+
+    while (jsonString[index] === '\\') {
+        index -= 1;
+        backslashCount += 1;
+    }
+
+    return Boolean(backslashCount % 2);
+};
+
+export function stripJsonComments(jsonString: string, {whitespace = true} = {}) {
+    if (typeof jsonString !== 'string') {
+        throw new TypeError(`Expected argument \`jsonString\` to be a \`string\`, got \`${typeof jsonString}\``);
+    }
+
+    const strip = whitespace ? stripWithWhitespace : stripWithoutWhitespace;
+
+    let isInsideString = false;
+    let isInsideComment = false;
+    let offset = 0;
+    let result = '';
+
+    for (let index = 0; index < jsonString.length; index++) {
+        const currentCharacter = jsonString[index];
+        const nextCharacter = jsonString[index + 1];
+
+        if (!isInsideComment && currentCharacter === '"') {
+            const escaped = isEscaped(jsonString, index);
+            if (!escaped) {
+                isInsideString = !isInsideString;
+            }
+        }
+
+        if (isInsideString) {
+            continue;
+        }
+
+        if (!isInsideComment && currentCharacter + nextCharacter === '//') {
+            result += jsonString.slice(offset, index);
+            offset = index;
+            isInsideComment = singleComment;
+            index++;
+        } else if (isInsideComment === singleComment && currentCharacter + nextCharacter === '\r\n') {
+            index++;
+            isInsideComment = false;
+            result += strip(jsonString, offset, index);
+            offset = index;
+            continue;
+        } else if (isInsideComment === singleComment && currentCharacter === '\n') {
+            isInsideComment = false;
+            result += strip(jsonString, offset, index);
+            offset = index;
+        } else if (!isInsideComment && currentCharacter + nextCharacter === '/*') {
+            result += jsonString.slice(offset, index);
+            offset = index;
+            isInsideComment = multiComment;
+            index++;
+            continue;
+        } else if (isInsideComment === multiComment && currentCharacter + nextCharacter === '*/') {
+            index++;
+            isInsideComment = false;
+            result += strip(jsonString, offset, index + 1);
+            offset = index + 1;
+            continue;
+        }
+    }
+
+    return result + (isInsideComment ? (strip as any)(jsonString.slice(offset)) : jsonString.slice(offset));
+}

package/tsconfig.json

@@ -73,5 +73,5 @@
     "skipLibCheck": true,                     /* Skip type checking of declaration files. */
     "forceConsistentCasingInFileNames": true  /* Disallow inconsistently-cased references to the same file. */
   },
-  "include": ["src", "api/structures"]
+  // "include": ["src", "test"]
 }