docs: add explanation ManyToMany with custom properties (typeorm#4308)

maxsommer · pleerock · commit c8a9ea083cc4 · 2019-06-30T18:12:07.000+03:00
* Add explanation ManyToMany with custom properties

Since I myself ran into the issue and had to rewrite my code based on this solution I hope it may be helpful for others as well 😊

* Update explanation with more relateable example

Update explanation with abstract example to be more relateable
Add cross link to faq

* Update phrasing, unnecessary explanation and code

Remove unnecessary explanation upfront mentioning FAQ
Update phrasing of main explanatory paragraph to be more precise
Update code example to work correctly
diff --git a/docs/faq.md b/docs/faq.md
@@ -131,7 +131,7 @@ join column / junction table settings, like join column name or junction table n
 It's not possible to add extra columns into a table created by a many-to-many relation.
 You'll need to create a separate entity and bind it using two many-to-one relations with the target entities
 (the effect will be same as creating a many-to-many table), 
-and add extra columns in there.
+and add extra columns in there. You can read more about this in [Many-to-Many relations](./many-to-many-relations.md#many-to-many-relations-with-custom-properties).
 
 ## How to use TypeORM with a dependency injection tool?
 
diff --git a/docs/many-to-many-relations.md b/docs/many-to-many-relations.md
@@ -169,3 +169,40 @@ const categoriesWithQuestions = await connection
     .leftJoinAndSelect("category.questions", "question")
     .getMany();
 ```
+
+## many-to-many relations with custom properties
+
+In case you need to have additional properties to your many-to-many relationship you have to create a new entity yourself. 
+For example if you would like entities `Post` and `Category` to have a many-to-many relationship with a `createdAt` property 
+associated to it you have to create entity `PostToCategory` like the following:
+
+```typescript
+import { Entity, Column, ManyToOne, PrimaryGeneratedColumn } from "typeorm";
+import { Post } from "./post";
+import { Category } from "./category";
+
+@Entity()
+export class PostToCategory {
+    @PrimaryGeneratedColumn()
+    public postToCategoryId!: number;
+
+    public postId!: number;
+    public categoryId!: number;
+
+    @Column()
+    public order!: number;
+
+    @ManyToOne(type => Post, post => post.postToCategories)
+    public post!: Post;
+
+    @ManyToOne(type => Category, category => category.postToCategories)
+    public category!: Category;
+}
+```
+
+Additionally you will have to add a relationship like the following to `Post` and `Category`:
+
+```typescript
+@OneToMany((type) => PostToCategory, (postToCategory) => postToCategory.post)
+public postToCategories!: PostToCategory[];
+```
