nestjs-telegraf/README.md

132 lines
3.9 KiB
Markdown
Raw Normal View History

## Description
2020-03-28 00:08:58 +03:00
[Telegraf](https://github.com/telegraf/telegraf) module for [NestJS](https://github.com/nestjs/nest).
## Installation
```bash
2020-03-19 20:50:04 +03:00
$ npm i nestjs-telegraf
2019-07-16 18:56:02 +03:00
```
2020-03-19 20:50:04 +03:00
Once the installation process is complete, we can import the TelegrafModule into the root AppModule.
2020-01-24 10:31:15 +03:00
```typescript
2020-03-19 20:50:04 +03:00
/* app.module.ts */
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
import { Module } from '@nestjs/common';
import { TelegrafModule } from 'nestjs-telegraf';
2020-01-24 10:31:15 +03:00
@Module({
imports: [
2020-03-19 20:50:04 +03:00
TelegrafModule.forRoot({
token: 'TELEGRAM_BOT_TOKEN',
})
2020-01-24 10:31:15 +03:00
],
})
2020-03-19 20:50:04 +03:00
export class AppModule {}
2020-01-24 10:31:15 +03:00
```
2020-03-19 20:50:04 +03:00
The `forRoot()` method accepts the same configuration object as Telegraf class constructor from the Telegraf package, as described [here](https://telegraf.js.org/#/?id=constructor).
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
## Telegraf methods
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
Each Telegraf instance method described [here](https://telegraf.js.org/#/?id=telegraf) has own decorator in `nestjs-telegraf` package. The name of the decorator corresponds to the name of the Telegraf method and starts with `Telegraf`. For example [`@TelegrafHears`](https://telegraf.js.org/#/?id=hears), [`@TelegrafOn`](https://telegraf.js.org/#/?id=on), [`@TelegrafAction`](https://telegraf.js.org/#/?id=action) and so on.
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
Now let's try to repeat the example from the Telegraf [documentation page](https://telegraf.js.org/#/?id=example).
2020-01-24 10:31:15 +03:00
```typescript
2020-03-19 20:50:04 +03:00
/* app.service.ts */
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
import { Injectable } from '@nestjs/common';
import {
TelegrafStart,
TelegrafHelp,
TelegrafOn,
TelegrafHears,
ContextMessageUpdate,
} from 'nestjs-telegraf';
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
@Injectable()
export class AppService {
@TelegrafStart()
start(ctx: ContextMessageUpdate) {
ctx.reply('Welcome');
}
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
@TelegrafHelp()
help(ctx: ContextMessageUpdate) {
ctx.reply('Send me a sticker');
}
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
@TelegrafOn('sticker')
on(ctx: ContextMessageUpdate) {
ctx.reply('👍');
}
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
@TelegrafHears('hi')
hears(ctx: ContextMessageUpdate) {
ctx.reply('Hey there');
2020-01-24 10:31:15 +03:00
}
}
```
2020-03-19 20:50:04 +03:00
## Async configuration
When you need to pass module options asynchronously instead of statically, use the forRootAsync() method. As with most dynamic modules, Nest provides several techniques to deal with async configuration.
2020-01-24 10:31:15 +03:00
2020-03-19 20:50:04 +03:00
One technique is to use a factory function:
2020-02-29 13:27:29 +03:00
```typescript
2020-03-19 20:50:04 +03:00
TelegrafModule.forRootAsync({
useFactory: () => ({
token: 'TELEGRAM_BOT_TOKEN',
}),
});
```
2020-02-29 13:27:29 +03:00
2020-03-19 20:50:04 +03:00
Like other [factory providers](https://docs.nestjs.com/fundamentals/custom-providers#factory-providers-usefactory), our factory function can be async and can inject dependencies through inject.
2020-02-29 13:27:29 +03:00
2020-03-19 20:50:04 +03:00
```typescript
TelegrafModule.forRootAsync({
imports: [ConfigModule],
useFactory: async (configService: ConfigService) => ({
2020-03-28 00:08:58 +03:00
token: configService.get<string>('TELEGRAM_BOT_TOKEN'),
2020-02-29 13:27:29 +03:00
}),
2020-03-19 20:50:04 +03:00
inject: [ConfigService],
});
2020-02-29 13:27:29 +03:00
```
2020-03-19 20:50:04 +03:00
Alternatively, you can configure the TelegrafModule using a class instead of a factory, as shown below:
2020-02-29 13:27:29 +03:00
2020-03-19 20:50:04 +03:00
```typescript
TelegrafModule.forRootAsync({
useClass: TelegrafConfigService,
});
```
2020-02-29 13:27:29 +03:00
2020-03-19 20:50:04 +03:00
The construction above instantiates `TelegrafConfigService` inside `TelegrafModule`, using it to create the required options object. Note that in this example, the `TelegrafConfigService` has to implement the `TelegrafOptionsFactory` interface, as shown below. The `TelegrafModule` will call the `createTelegrafOptions()` method on the instantiated object of the supplied class.
2020-02-29 13:27:29 +03:00
2020-03-19 20:50:04 +03:00
```typescript
2020-02-29 13:27:29 +03:00
@Injectable()
2020-03-19 20:50:04 +03:00
class TelegrafConfigService implements TelegrafOptionsFactory {
createMongooseOptions(): TelegrafModuleOptions {
2020-02-29 13:27:29 +03:00
return {
2020-03-19 20:50:04 +03:00
token: 'TELEGRAM_BOT_TOKEN',
2020-02-29 13:27:29 +03:00
};
}
}
```
2020-03-19 20:50:04 +03:00
If you want to reuse an existing options provider instead of creating a private copy inside the `TelegrafModule`, use the `useExisting` syntax.
2020-01-24 10:31:15 +03:00
```typescript
2020-03-19 20:50:04 +03:00
TelegrafModule.forRootAsync({
imports: [ConfigModule],
useExisting: ConfigService,
});
2020-01-24 10:31:15 +03:00
```
## People
2019-07-16 18:56:02 +03:00
2020-03-28 00:08:58 +03:00
- Authors - [robotmafia Inc.](https://robotmafia.io) & [Aleksandr Bukhalo](https://bukhalo.com/) & [Igor Kamyshev](https://kamyshev.me/)
- Maintainers - [robotmafia Inc.](https://robotmafia.io/)