Merge pull request #89 from samchon/features/docs

Write README again

Author: samchon

.npmignore

@@ -1,11 +1,11 @@
 {
   "name": "safe-typeorm",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Make TypeORM much safer",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "scripts": {
-    "build": "rimraf lib && tsc",
+    "build": "rimraf lib && ttsc",
     "dev": "npm run build -- --watch",
     "eslint": "eslint src",
     "eslint:fix": "eslint src --fix",
@@ -29,7 +29,7 @@
   "dependencies": {
     "bcryptjs": "^2.4.3",
     "pluralize": "^8.0.0",
-    "tstl": "^2.5.2",
+    "tstl": "^2.5.13",
     "typeorm": "^0.2.41",
     "uuid": "^8.3.2"
   },
@@ -50,6 +50,17 @@
     "sloc": "^0.2.1",
     "sqlite3": "^5.0.2",
     "ts-node": "^9.1.1",
-    "typescript": "^4.5.2"
-  }
+    "ttypescript": "^1.5.15",
+    "typescript": "^4.5.2",
+    "typescript-transform-paths": "^3.4.6"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "package.json",
+    "lib",
+    "src",
+    "!lib/test",
+    "!src/test"
+  ]
 }

README.md

@@ -15,9 +15,9 @@ import { insert } from "./functional/insert";
 import { toPrimitive } from "./functional/toPrimitive";
 import { update } from "./functional/update";
 
-import { FieldLike } from "./typings/FieldLike";
 import { Creator as _Creator } from "./typings/Creator";
 import { Field } from "./typings/Field";
+import { FieldLike } from "./typings/FieldLike";
 import { Initialized } from "./typings/Initialized";
 import { OmitNever } from "./typings/OmitNever";
 import { Operator } from "./typings/Operator";

assets/demonstrations/safe-query-builder.gif renamed to assets/demonstrations/join-query-builder-onetime.gif

@@ -0,0 +1,21 @@
+import safe from "safe-typeorm";
+
+import { BbsReviewArticle } from "../models/bbs/BbsReviewArticle";
+
+export async function test_app_join_builder_initialize(
+    reviews: BbsReviewArticle[],
+): Promise<void> {
+    const builder = safe.createAppJoinBuilder(BbsReviewArticle, (review) => {
+        review.join("base", (article) => {
+            article.join("group");
+            article.join("category").join("parent");
+            article.join("contents", (content) => {
+                content.join("reviewContent");
+                content.join("files");
+            });
+            article.join("comments").join("files");
+            article.join("tags");
+        });
+    });
+    await builder.execute(reviews);
+}

assets/demonstrations/join-query-builder.gif

@@ -0,0 +1,36 @@
+import safe from "safe-typeorm";
+
+import { BbsArticle } from "../models/bbs/BbsArticle";
+import { BbsArticleContent } from "../models/bbs/BbsArticleContent";
+import { BbsComment } from "../models/bbs/BbsComment";
+import { BbsGroup } from "../models/bbs/BbsGroup";
+import { BbsReviewArticle } from "../models/bbs/BbsReviewArticle";
+
+export async function test_app_join_builder_initialize(
+    groups: BbsGroup[],
+): Promise<void> {
+    const builder = safe.AppJoinBuilder.initialize(BbsGroup, {
+        articles: safe.AppJoinBuilder.initialize(BbsArticle, {
+            group: undefined,
+            review: safe.AppJoinBuilder.initialize(BbsReviewArticle, {
+                base: undefined,
+            }),
+            category: "join" as const,
+            contents: safe.AppJoinBuilder.initialize(BbsArticleContent, {
+                files: "join" as const,
+                article: undefined,
+                reviewContent: undefined,
+            }),
+            comments: safe.AppJoinBuilder.initialize(BbsComment, {
+                article: undefined,
+                files: "join",
+            }),
+            tags: "join",
+            __mv_last: undefined,
+            question: undefined,
+            answer: undefined,
+            scraps: undefined,
+        }),
+    });
+    await builder.execute(groups);
+}

package.json

@@ -0,0 +1,38 @@
+import safe from "safe-typeorm";
+import * as orm from "typeorm";
+
+import { BbsGroup } from "../models/bbs/BbsGroup";
+import { BbsQuestionArticle } from "../models/bbs/BbsQuestionArticle";
+
+export function demo_join_query_builder(
+    group: BbsGroup,
+    exclude: string[],
+): orm.SelectQueryBuilder<BbsQuestionArticle> {
+    const question = safe.createJoinQueryBuilder(BbsQuestionArticle);
+
+    // JOIN
+    const article = question.innerJoin("base");
+    const content = article.innerJoin("__mv_last").innerJoin("content");
+    const category = article.innerJoin("category");
+
+    // SELECT
+    article.addSelect("id").addSelect("writer").addSelect("created_at");
+    content.addSelect("title").addSelect("created_at", "updated_at");
+    article.leftJoin("answer").leftJoin("base", "AA", (answer) => {
+        answer.addSelect("writer", "answer_writer");
+        answer.addSelect("created_at", "answer_created_at");
+        answer
+            .leftJoin("__mv_last", "AL")
+            .leftJoin("content", "AC")
+            .addSelect(
+                ["title", (str) => `COALESCE(${str}, 'NONE')`],
+                "answer_title",
+            );
+    });
+    content.addOrderBy("created_at", "DESC");
+
+    // WHERE
+    article.andWhere("group", group);
+    category.andWhere("code", "NOT IN", exclude);
+    return question.statement();
+}

src/Model.ts

@@ -0,0 +1,44 @@
+import safe from "safe-typeorm";
+import * as orm from "typeorm";
+
+import { BbsArticle } from "../models/bbs/BbsArticle";
+import { BbsArticleContent } from "../models/bbs/BbsArticleContent";
+import { BbsCategory } from "../models/bbs/BbsCategory";
+import { BbsGroup } from "../models/bbs/BbsGroup";
+import { BbsQuestionArticle } from "../models/bbs/BbsQuestionArticle";
+
+export function demo_join_query_builder_onetime(
+    group: BbsGroup,
+    exclude: string[],
+): orm.SelectQueryBuilder<BbsQuestionArticle> {
+    return safe
+        .createJoinQueryBuilder(BbsQuestionArticle, (question) => {
+            question.innerJoin("base", (article) => {
+                article.innerJoin("group");
+                article.innerJoin("category");
+                article.innerJoin("__mv_last").innerJoin("content");
+            });
+            question
+                .leftJoin("answer")
+                .leftJoin("base", "AA")
+                .leftJoin("__mv_last", "AL")
+                .leftJoin("content", "AC");
+        })
+        .statement()
+        .andWhere(...BbsArticle.getWhereArguments("group", group))
+        .andWhere(...BbsCategory.getWhereArguments("code", "NOT IN", exclude))
+        .select([
+            BbsArticle.getColumn("id"),
+            BbsGroup.getColumn("name", "group"),
+            BbsCategory.getColumn("name", "category"),
+            BbsArticle.getColumn("writer"),
+            BbsArticleContent.getColumn("title"),
+            BbsArticle.getColumn("created_at"),
+            BbsArticleContent.getColumn("created_at", "updated_at"),
+
+            BbsArticle.getColumn("AA.writer", "answer_writer"),
+            BbsArticleContent.getColumn("AA.title", "answer_title"),
+            BbsArticle.getColumn("AA.created_at", "answer_created_at"),
+        ])
+        .orderBy(BbsArticleContent.getColumn("created_at", null), "DESC");
+}

src/test/demo/demo_app_join_builder.ts

@@ -0,0 +1,30 @@
+import safe from "safe-typeorm";
+
+import { BbsArticle } from "../models/bbs/BbsArticle";
+import { BbsArticleContent } from "../models/bbs/BbsArticleContent";
+import { BbsArticleTag } from "../models/bbs/BbsArticleTag";
+import { BbsCategory } from "../models/bbs/BbsCategory";
+import { BbsGroup } from "../models/bbs/BbsGroup";
+import { IBbsGroup } from "../structures/IBbsGroup";
+
+export async function demo_app_join_builder(
+    groups: BbsGroup[],
+): Promise<IBbsGroup[]> {
+    const builder = new safe.JsonSelectBuilder(BbsGroup, {
+        articles: new safe.JsonSelectBuilder(BbsArticle, {
+            group: safe.DEFAULT,
+            category: new safe.JsonSelectBuilder(BbsCategory, {
+                parent: "recursive" as const,
+            }),
+            tags: new safe.JsonSelectBuilder(
+                BbsArticleTag,
+                {},
+                (tag) => tag.value, // OUTPUT CONVERSION BY MAPPING
+            ),
+            contents: new safe.JsonSelectBuilder(BbsArticleContent, {
+                files: "join" as const,
+            }),
+        }),
+    });
+    return builder.getMany(groups);
+}

src/test/demo/demo_app_join_builder_initialize.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { Relationship } from "../../typings";
 import { generate_random_clean_groups } from "../internal/generators/generate_random_clean_groups";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";

src/test/demo/demo_join_query_builder.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import * as orm from "typeorm";
 
-import safe from "../..";
 import { generate_random_clean_groups } from "../internal/generators/generate_random_clean_groups";
 import { BbsArticle } from "../models/bbs/BbsArticle";
 import { BbsGroup } from "../models/bbs/BbsGroup";

src/test/demo/demo_join_query_builder_onetime.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { generate_random_clean_groups } from "../internal/generators/generate_random_clean_groups";
 import { iterate_bbs_group } from "../internal/iterators/iterate_bbs_group";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";

src/test/demo/demo_json_select_builder.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { generate_random_bbs_review_articles as generate_random_reviews } from "../internal/generators/generate_random_bbs_review_articles";
 import { iterate_bbs_review_article } from "../internal/iterators/iterate_bbs_review_article";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";

src/test/features/test_app_join.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { generate_random_external_db } from "../internal/generators/generate_random_external_db";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";
 import { BbsGroup } from "../models/bbs/BbsGroup";

src/test/features/test_app_join_builder_filter.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { collect_random_external_db } from "../internal/collectors/collect_random_external_db";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";
 

src/test/features/test_app_join_builder_initialize.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { collect_random_external_db } from "../internal/collectors/collect_random_external_db";
 import { iterate_bbs_group } from "../internal/iterators/iterate_bbs_group";
 import { BbsGroup } from "../models/bbs/BbsGroup";

src/test/features/test_create_app_join_builder.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { generate_random_normal_bbs_group } from "../internal/generators/generate_random_normal_bbs_group";
 import { BbsGroup } from "../models/bbs/BbsGroup";
 

src/test/features/test_external_app_join_builder.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { BbsGroup } from "../models/bbs/BbsGroup";
 import { IBbsGroup } from "../structures/IBbsGroup";
 import { test_json_select_builder } from "./test_json_select_builder";

src/test/features/test_external_insert_collection.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import { equal } from "tstl/ranges/algorithm";
 
-import safe from "../..";
 import { ArrayUtil } from "../../utils/ArrayUtil";
 import { generate_random_clean_groups } from "../internal/generators/generate_random_clean_groups";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";

src/test/features/test_external_relation_getter.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import * as orm from "typeorm";
 
-import safe from "../..";
 import { generate_random_clean_groups } from "../internal/generators/generate_random_clean_groups";
 import { BbsArticle } from "../models/bbs/BbsArticle";
 import { BbsGroup } from "../models/bbs/BbsGroup";

src/test/features/test_join_query_builder_duplicated_join.ts

@@ -1,6 +1,7 @@
+import safe from "safe-typeorm";
+
 import { IPointer } from "tstl/functional/IPointer";
 
-import safe from "../..";
 import { generate_random_recursive_category } from "../internal/generators/generate_radom_recursive_category";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";
 import { BbsCategory } from "../models/bbs/BbsCategory";

src/test/features/test_join_query_builder_where.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { generate_random_recursive_category } from "../internal/generators/generate_radom_recursive_category";
 import { must_not_query_anything } from "../internal/procedures/must_not_query_anything";
 import { BbsCategory } from "../models/bbs/BbsCategory";

src/test/features/test_json_select_builder.ts

@@ -1,4 +1,5 @@
-import safe from "../..";
+import safe from "safe-typeorm";
+
 import { BbsCategory } from "../models/bbs/BbsCategory";
 import { test_recursive_app_join_builder_belongs_to } from "./test_recursive_app_join_builder_belongs_to";
 

src/test/features/test_json_select_builder_filter.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import orm from "typeorm";
 
-import safe from "../..";
 import { BbsArticle } from "../models/bbs/BbsArticle";
 import { BbsArticleContent } from "../models/bbs/BbsArticleContent";
 import { BbsCategory } from "../models/bbs/BbsCategory";

src/test/features/test_recursive_app_join_builder_belongs_to.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import { randint } from "tstl";
 
-import safe from "../../..";
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 import { BbsArticle } from "../../models/bbs/BbsArticle";
 import { BbsArticleContent } from "../../models/bbs/BbsArticleContent";

src/test/features/test_recursive_app_join_builder_has_one_to_many.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import { randint } from "tstl";
 
-import safe from "../../..";
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 import { AttachmentFile } from "../../models/bbs/AttachmentFile";
 import { BbsArticle } from "../../models/bbs/BbsArticle";

src/test/features/test_recursive_json_select_builder.ts

@@ -1,6 +1,6 @@
+import safe from "safe-typeorm";
 import { randint } from "tstl/algorithm/random";
 
-import safe from "../../..";
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 import { AttachmentFile } from "../../models/bbs/AttachmentFile";
 import { BbsArticle } from "../../models/bbs/BbsArticle";

src/test/features/test_safe_query_builder.ts

@@ -1,4 +1,5 @@
-import safe from "../../..";
+import safe from "safe-typeorm";
+
 import { BbsArticle } from "../../models/bbs/BbsArticle";
 import { BbsReviewArticle } from "../../models/bbs/BbsReviewArticle";
 import { BbsReviewArticleContent } from "../../models/bbs/BbsReviewArticleContent";

src/test/internal/collectors/collect_random_bbs_article.ts

@@ -1,4 +1,5 @@
-import safe from "../../..";
+import safe from "safe-typeorm";
+
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 import { BbsArticle } from "../../models/bbs/BbsArticle";
 import { BbsGroup } from "../../models/bbs/BbsGroup";

src/test/internal/collectors/collect_random_bbs_article_content.ts

@@ -1,4 +1,5 @@
-import safe from "../../..";
+import safe from "safe-typeorm";
+
 import { ArrayUtil } from "../../../utils/ArrayUtil";
 import { BbsCategory } from "../../models/bbs/BbsCategory";
 import { RandomGenerator } from "../procedures/RandomGenerator";