Graphile Worker for Nest.js

A Nest.js wrapper for Graphile Worker.

What is Graphile worker ?

Job queue for PostgreSQL running on Node.js - allows you to run jobs (e.g. sending emails, performing calculations, generating PDFs, etc) "in the background" so that your HTTP response/application code is not held up. Can be used with any PostgreSQL-backed application. Pairs beautifully with PostGraphile or PostgREST.

Why you should prefer Graphile Worker instead of Bull ?

1. You already have a PostgreSQL in your stack (and you don't want to add a Redis server)

Features

• use a GraphileWorkerModule.forRoot to register Graphile Worker (support asRootAsync as well)
• provide a WorkerService to add jobs or start runner
• provide a @OnWorkerEvent decorator to add custom behavior on job:success for example
• provide a @Task(name) decorator to define your injectable tasks

Installation

1npm install nestjs-graphile-worker

Usage

Import module

You can use GraphileWorkerModule.forRoot:

1// src/app.module.ts
2import { GraphileWorkerModule } from "nest-graphile-worker";
3import { Module } from "@nestjs/common";
4import { AppController } from "./app.controller";
5
6@Module({
7  imports: [
8    GraphileWorkerModule.forRoot({
9      connectionString: "postgres://example:password@postgres/example",
10    }),
11  ],
12  controllers: [AppController],
13  providers: [],
14})
15export class AppModule {}

Or you can use GraphileWorkerModule.forRootAsync:

1import { GraphileWorkerModule } from "nestjs-graphile-worker";
2import { Module } from "@nestjs/common";
3import { ConfigModule, ConfigService } from "@nestjs/config";
4import { AppController } from "./app.controller";
5import { helloTask } from "./hello.task";
6
7@Module({
8  imports: [
9    ConfigModule.forRoot(),
10    GraphileWorkerModule.forRootAsync({
11      imports: [ConfigModule],
12      inject: [ConfigService],
13      useFactory: (config: ConfigService) => ({
14        connectionString: config.get("PG_CONNECTION"),
15        taskList: {
16          hello: helloTask,
17        },
18      }),
19    }),
20  ],
21  controllers: [AppController],
22  providers: [],
23})
24export class AppModule {}

Create task

To create task you need to define an @Injectable class with @Task(name) decorator who contains a decorated method @TaskHandler:

1import { Injectable, Logger } from "@nestjs/common";
2import type { Helpers } from "graphile-worker";
3import { Task, TaskHandler } from "../../src/index";
4
5@Injectable()
6@Task("hello")
7export class HelloTask {
8  private logger = new Logger(HelloTask.name);
9
10  @TaskHandler()
11  handler(payload: any, _helpers: Helpers) {
12    this.logger.log(`handle ${JSON.stringify(payload)}`);
13  }
14}

Then do not forget to register this class as provider in your module:

1import { Module } from "@nestjs/common";
2import { HelloTask } from "./hello.task";
3// ...
4
5@Module({
6  imports: [
7    /* ... */
8  ],
9  controllers: [
10    /* ... */
11  ],
12  providers: [HelloTask],
13})
14export class AppModule {}

Create jobs

You may use WorkerService:

1import { WorkerService } from "nestjs-graphile-worker";
2import { Controller, HttpCode, Post } from "@nestjs/common";
3
4@Controller()
5export class AppController {
6  constructor(private readonly graphileWorker: WorkerService) {}
7
8  @Post()
9  @HttpCode(201)
10  async addJob() {
11    await this.graphileWorker.addJob("hello", { hello: "world" });
12  }
13
14  @Post("bulk")
15  @HttpCode(201)
16  async addJobs() {
17    const jobs = new Array(100)
18      .fill(undefined)
19      .map((_, i) => ({ identifier: "hello", payload: { hello: i } }));
20
21    return this.graphileWorker.addJobs(jobs);
22  }
23}

Start runner

Add WorkerService.run in main.ts file:

1import { WorkerService } from "nestjs-graphile-worker";
2import { NestFactory } from "@nestjs/core";
3import { AppModule } from "./app.module";
4
5async function bootstrap() {
6  const app = await NestFactory.create(AppModule);
7  app.get(WorkerService).run();
8  await app.listen(3000);
9}
10bootstrap();

OnWorkerEvent decorator

This decorator allow you to listen all Graphile Worker event

You need to add @GraphileWorkerListener decorator on your class and then set @OnWorkerEvent(eventName) on method:

1import { Injectable, Logger } from "@nestjs/common";
2import { WorkerEventMap } from "graphile-worker";
3import { GraphileWorkerListener, OnWorkerEvent } from "../../src/index";
4
5@Injectable()
6@GraphileWorkerListener()
7export class AppService {
8  private readonly logger = new Logger(AppService.name);
9
10  @OnWorkerEvent("job:success")
11  onJobSuccess({ job }: WorkerEventMap["job:success"]) {
12    this.logger.debug(`job #${job.id} finished`);
13  }
14
15  @OnWorkerEvent("job:error")
16  onJobError({ job, error }: WorkerEventMap["job:error"]) {
17    this.logger.error(`job #${job.id} fail ${JSON.stringify(error)}`);
18  }
19}

Test

1# unit tests
2$ npm run test
3
4# test coverage
5$ npm run test:cov

Sample

You can find a sample who use library. To run it, simply npm install and then:

1docker-compose up