Skip to content

Commit ffc9cca

Browse files
NoNameProvidedNoNameProvided
committed
docs: update README formatting
1 parent 2a374ed commit ffc9cca

File tree

1 file changed

+94
-148
lines changed

1 file changed

+94
-148
lines changed

‎README.md

Lines changed: 94 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,216 +1,162 @@
11
# TypeDI Service container integration with TypeORM
22

3-
This extension for TypeORM provides handy decorators that can be used with [typedi](https://github.com/pleerock/typedi).
3+
![Build Status](https://github.com/typeorm/typeorm-typedi-extensions/workflows/CI/badge.svg)
4+
[![npm version](https://badge.fury.io/js/typeorm-typedi-extensions.svg)](https://badge.fury.io/js/typeorm-typedi-extensions)
5+
[![Dependency Status](https://david-dm.org/typeorm/typeorm-typedi-extensions.svg)](https://david-dm.org/typeorm/typeorm-typedi-extensions)
6+
7+
This package provides decorators for TypeORM that can be used with [TypeDI](https://github.com/pleerock/typedi).
48

59
## Installation
610

7-
* Install module:
11+
To start using TypeDI install the required packages via NPM:
812

9-
`npm install typeorm-typedi-extensions --save`
13+
```bash
14+
npm install typeorm-typedi-extensions typedi reflect-metadata
15+
```
1016

11-
* Install TypeDI:
17+
Import the `reflect-metadata` package at the **first line** of your application:
1218

13-
`npm install typedi --save`
19+
```ts
20+
import 'reflect-metadata';
1421

15-
* Configure in your app TypeORM to use TypeDI Container, before you create a connection:
22+
// Your other imports and initialization code
23+
// comes here after you imported the reflect-metadata package!
24+
```
1625

17-
```typescript
18-
import "reflect-metadata";
19-
import {createConnection, useContainer} from "typeorm";
20-
import {Container} from "typedi";
26+
You need to enable emitting decorator metadata in your Typescript config. Add these two lines to your `tsconfig.json` file under the `compilerOptions` key:
2127

22-
useContainer(Container);
23-
createConnection({
24-
/// ....
25-
});
28+
```json
29+
"emitDecoratorMetadata": true,
30+
"experimentalDecorators": true,
2631
```
2732

28-
* That's all, start using decorators!
33+
Configure TypeORM in your app to use the TypeDI container before you create a connection:
34+
35+
```ts
36+
import { createConnection, useContainer } from 'typeorm';
37+
import { Container } from 'typedi';
38+
39+
/** Tell TypeORM to use the TypeDI container to resolve it's dependencies. */
40+
useContainer(Container);
2941

42+
/** Create a connection and start using TypeORM. */
43+
createConnection({ /* <connection options> */})
44+
.catch(error => {
45+
console.error(`Couldn't connect to the database!`);
46+
console.error(error);
47+
});
48+
```
3049

3150
## Usage
3251

33-
All decorators can be used on properties and constructor arguments, e.g. you can use both
34-
property and constructor injection.
52+
This package exposes three decorators all three decorators can be used on properties or on constructor parameters.
3553

36-
### @InjectConnection
54+
> **IMPORTANT:**
55+
> To allow TypeDI to resolve the dependencies on your classes you must mark them with `@Service` decorator from the TypeDI package.
3756
38-
Injects `Connection` from where you can access anything in your connection.
57+
### `@InjectConnection` decorator
3958

40-
Example using property injection:
59+
Injects `Connection` from where you can access anything in your connection.
60+
Optionally, you can specify a connection to inject by name in the decorator parameter.
4161

4262
```typescript
43-
import {Service} from "typedi";
44-
import {Connection} from "typeorm";
45-
import {InjectConnection} from "typeorm-typedi-extensions";
63+
import { Service } from 'typedi';
64+
import { Connection } from 'typeorm';
65+
import { InjectConnection } from 'typeorm-typedi-extensions';
4666

4767
@Service()
48-
export class PostRepository {
49-
50-
@InjectConnection()
51-
private connection: Connection;
52-
53-
}
54-
```
68+
export class MyCustomClass {
5569

56-
Example using constructor injection:
70+
@InjectConnection()
71+
private propertyInjectedConnection: Connection;
5772

58-
```typescript
59-
import {Service} from "typedi";
60-
import {Connection} from "typeorm";
61-
import {InjectConnection} from "typeorm-typedi-extensions";
62-
63-
@Service()
64-
export class PostRepository {
65-
66-
constructor(@InjectConnection() private connection: Connection) {
67-
}
68-
73+
constructor(@InjectConnection() private constructorInjectedConnection: Connection) {}
6974
}
7075
```
7176

72-
Optionally, you can specify a connection name in the decorator parameters.
77+
### `@InjectManager` decorator
7378

74-
### @InjectManager
79+
Injects `EntityManager` from where you can access any entity in your connection.
80+
Optionally, you can specify a connection to inject by name in the decorator parameter.
7581

76-
Injects `EntityManager` from where you can access any entity in your connection.
77-
78-
Example using property injection:
79-
80-
```typescript
81-
import {Service} from "typedi";
82-
import {EntityManager} from "typeorm";
83-
import {InjectManager} from "typeorm-typedi-extensions";
82+
```ts
83+
import { Service } from 'typedi';
84+
import { EntityManager } from 'typeorm';
85+
import { InjectManager } from 'typeorm-typedi-extensions';
8486

8587
@Service()
86-
export class PostRepository {
87-
88-
@InjectManager()
89-
private entityManager: EntityManager;
90-
91-
}
92-
```
88+
export class MyCustomClass {
9389

94-
Example using constructor injection:
95-
96-
```typescript
97-
import {Service} from "typedi";
98-
import {EntityManager} from "typeorm";
99-
import {InjectManager} from "typeorm-typedi-extensions";
90+
@InjectManager()
91+
private propertyInjectedEntityManager: EntityManager;
10092

101-
@Service()
102-
export class PostRepository {
103-
104-
constructor(@InjectManager() private entityManager: EntityManager) {
105-
}
106-
93+
constructor(@InjectManager() private constructorInjectedEntityManager: EntityManager) {}
10794
}
10895
```
10996

110-
Optionally, you can specify a connection name in the decorator parameters.
111-
112-
### @InjectRepository
97+
### `@InjectRepository` decorator
11398

11499
Injects `Repository`, `MongoRepository`, `TreeRepository` or custom repository of some Entity.
115-
Be aware that the property or param decorated with `@InjectRepository` has to be annotated with repository type!
116-
117-
Example using property injection:
100+
Optionally, you can specify a connection to inject by name in the decorator parameter.
118101

119102
```typescript
120-
import {Service} from "typedi";
121-
import {Repository} from "typeorm";
122-
import {InjectRepository} from "typeorm-typedi-extensions";
123-
import "../entity/Post";
103+
import { Service } from 'typedi';
104+
import { Repository } from 'typeorm';
105+
import { InjectRepository } from 'typeorm-typedi-extensions';
106+
// MyDatabaseModel is a TypeORM entity (class marked with `@Entity()` decorator)
107+
import { MyDatabaseModel } from './entities/post.entity.ts';
124108

125109
@Service()
126-
export class PostRepository {
127-
128-
@InjectRepository(Post)
129-
private repository: Repository<Post>;
130-
131-
}
132-
```
110+
export class MyCustomClass {
133111

134-
Example using constructor injection:
112+
@InjectRepository(MyDatabaseModel)
113+
private propertyInjectedRepository: Repository<MyDatabaseModel>;
135114

136-
```typescript
137-
import {Service} from "typedi";
138-
import {Repository} from "typeorm";
139-
import {InjectRepository} from "typeorm-typedi-extensions";
140-
import "../entity/Post";
141-
142-
@Service()
143-
export class PostRepository {
144-
145-
constructor(
146-
@InjectRepository(Post)
147-
private repository: Repository<Post>
148-
) {}
149-
115+
constructor(@InjectRepository(MyDatabaseModel) private constructorInjectedRepository: Repository<MyDatabaseModel>) {}
150116
}
151117
```
152-
Optionally, you can specify a connection name in the decorator parameters:
118+
119+
Example with custom connection name:
153120

154121
```ts
155122
@Service()
156123
export class PostRepository {
157-
158-
@InjectRepository(Post, "custom-con-name")
159-
private repository: Repository<Post>;
160-
124+
@InjectRepository(Post, 'custom-con-name')
125+
private repository: Repository<Post>;
161126
}
162127
```
163128

164-
You can also inject custom `Repository` of some Entity.
165-
Be aware that you have to create the class which extends the generic `Repository<T>` and decorate it with `EntityRepository<T>` decorator.
129+
You can also inject custom `Repository` of some Entity. To make this work have to create the class which extends the
130+
generic `Repository<T>` class and decorate it with `EntityRepository<T>` decorator.
166131

167132
Example using constructor injection:
168133

169134
```typescript
170-
import { Service } from "typedi";
171-
import { Repository, EntityRepository } from "typeorm";
172-
import { InjectRepository } from "typeorm-typedi-extensions";
173-
import "../entity/user";
135+
import { Service } from 'typedi';
136+
import { Repository, EntityRepository } from 'typeorm';
137+
import { InjectRepository } from 'typeorm-typedi-extensions';
138+
// UserModel is a TypeORM entity (class marked with `@Entity()` decorator)
139+
import { UserModel } from './entities/user.entity.ts';
174140

175-
// create custom Repository class
176141
@Service()
177-
@EntityRepository(User)
178-
export class UserRepository extends Repository<User> {
179-
180-
public findByEmail(email: string) {
181-
return this.findOne({ email });
182-
}
183-
142+
@EntityRepository(UserModel)
143+
export class UserRepository extends Repository<UserModel> {
144+
public findByEmail(email: string) {
145+
return this.findOne({ email });
146+
}
184147
}
185148

186149
@Service()
187150
export class PostService {
188-
189-
// using constructor injection
190-
constructor(
191-
@InjectRepository()
192-
private readonly userRepository: UserRepository,
193-
) {}
194-
195-
public async userExist(user: User): boolean {
196-
return await this.userRepository.findByEmail(user.email) ? true : false;
197-
}
198-
151+
constructor(
152+
@InjectRepository()
153+
private readonly userRepository: UserRepository
154+
) {}
155+
156+
public async userExist(user: User): boolean {
157+
return (await this.userRepository.findByEmail(user.email)) ? true : false;
158+
}
199159
}
200160
```
201161

202-
Optionally, you can specify a connection name in the decorator parameters.
203-
204-
```ts
205-
@Service()
206-
export class PostService {
207-
208-
@InjectRepository("custom-con-name")
209-
private userRepository: UserRepository;
210-
211-
}
212-
```
213-
214-
## Samples
215-
216-
Take a look on samples in [./sample](sample) for examples of usages.
162+
[typedi]: https://github.com/typestack/typedi

0 commit comments

Comments
 (0)