@tsed/agenda 7.52.0 → 7.54.0

package/lib/types/AgendaModule.d.ts

@@ -1,14 +1,20 @@
 import { AfterListen, Logger, OnDestroy } from "@tsed/common";
 import { InjectorService, Provider } from "@tsed/di";
+import { Job } from "agenda";
 import { AgendaService } from "./services/AgendaFactory";
 export declare class AgendaModule implements OnDestroy, AfterListen {
     protected logger: Logger;
     protected injector: InjectorService;
     protected agenda: AgendaService;
-    private loadAgenda;
+    private enabled;
     private disableJobProcessing;
     $afterListen(): Promise<any>;
     $onDestroy(): Promise<any>;
+    define(name: string, options?: any, processor?: any): void;
+    every(interval: string, name: string, data?: any, options?: any): Promise<any>;
+    schedule(when: Date | string, name: string, data?: any): Promise<Job<import("agenda").JobAttributesData>>;
+    now(name: string, data?: any): Promise<Job<import("agenda").JobAttributesData>>;
+    create(name: string, data?: any): Job<import("agenda").JobAttributesData>;
     protected getProviders(): Provider<any>[];
     protected addAgendaDefinitionsForProvider(provider: Provider): void;
     protected scheduleJobsForProvider(provider: Provider<any>): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsed/agenda",
-  "version": "7.52.0",
+  "version": "7.54.0",
   "description": "Agenda package for Ts.ED framework",
   "source": "./src/index.ts",
   "main": "./lib/cjs/index.js",
@@ -25,9 +25,9 @@
   },
   "private": false,
   "devDependencies": {
-    "@tsed/common": "7.52.0",
-    "@tsed/core": "7.52.0",
-    "@tsed/di": "7.52.0",
+    "@tsed/common": "7.54.0",
+    "@tsed/core": "7.54.0",
+    "@tsed/di": "7.54.0",
     "@tsed/eslint": "7.44.1",
     "@tsed/typescript": "7.44.1",
     "agenda": "^4.1.3",

package/readme.md

@@ -82,7 +82,7 @@ method name is used as job name.
 Use the `@Define` decorator on methods that you would like to schedule
 programmatically via the AgendaService and Agenda instance access.
 
-```typescript
+```ts
 import {Agenda, Every, Define} from "@tsed/agenda";
 import {Job} from "agenda";
 
@@ -111,6 +111,52 @@ export class EmailJobService {
 }
 ```
 
+## Define a job processor manually
+
+Since Ts.ED 7.53.0, AgendaModule exposes methods to manually define a job processor. It can be useful to define a job processor when you need to fetch data beforehand and dynamically build job name / options.
+
+```typescript
+import {Agenda, AgendaModule, Define} from "@tsed/agenda";
+
+@Agenda({namespace: "email"})
+export class EmailJobService {
+  @Inject()
+  agenda: AgendaModule;
+
+  @Inject()
+  httpClient: HttpClient;
+
+  cache: Map<string, Job[]> = new Map();
+
+  @Define({
+    name: "sendWelcomeEmail",
+    concurrency: 3
+    /*  ... and any option you would normally pass to agenda.define(...) */
+  })
+  async sendWelcomeEmail(job: Job) {
+    // implement something here
+    console.log(job.attrs.data.locale);
+  }
+
+  async $beforeAgendaStart() {
+    const locales = await this.httpClient.get("/locales");
+
+    this.cache.set(
+      "sendWelcomeEmail",
+      locales.map((locale) => {
+        return this.agenda.create("sendWelcomeEmail", {locale});
+      })
+    );
+  }
+
+  async $afterAgendaStart() {
+    const jobs = this.cache.get("sendWelcomeEmail");
+
+    await Promise.all(jobs.map((job) => job.repeatEvery("1 week").save()));
+  }
+}
+```
+
 ## Inject Agenda
 
 Inject the AgendaService instance to interact with it directly, e.g. to schedule
@@ -118,12 +164,12 @@ a job manually.
 
 ```typescript
 import {Service, AfterRoutesInit} from "@tsed/common";
-import {AgendaService} from "@tsed/agenda";
+import {AgendaModule} from "@tsed/agenda";
 
 @Service()
-export class UsersService implements AfterRoutesInit {
+export class UsersService {
   @Inject()
-  private agenda: AgendaService;
+  private agenda: AgendaModule;
 
   async create(user: User): Promise<User> {
     // do something
@@ -137,6 +183,49 @@ export class UsersService implements AfterRoutesInit {
 }
 ```
 
+## Using Agendash
+
+[Agendash](https://github.com/agenda/agendash) provides a job overview dashboard that makes it easy to manage, create and
+schedule your jobs.
+
+::: tip Note
+This is an optional feature and is not required to use agenda.
+:::
+
+Install the additional dependency.
+
+```shell
+npm install --save agendash
+```
+
+Afterward create the module `agendash.module.ts` in src/modules so that the dashboard can be exposed using middleware.
+
+```typescript
+import {AfterRoutesInit, Inject, PlatformApplication} from "@tsed/common";
+import {Configuration, Module} from "@tsed/di";
+import {Agenda} from "agenda";
+
+const Agendash = require("agendash");
+
+@Module()
+export class AgendashModule implements AfterRoutesInit {
+  @Configuration()
+  config: Configuration;
+
+  @Inject()
+  agenda: Agenda;
+
+  @Inject()
+  app: PlatformApplication;
+
+  $afterRoutesInit() {
+    if (this.config.agenda?.enabled) {
+      this.app.use("/agendash", Agendash(this.agenda));
+    }
+  }
+}
+```
+
 ## Contributors
 
 Please read [contributing guidelines here](https://tsed.io/contributing.html)

package/src/AgendaModule.spec.ts

@@ -0,0 +1,198 @@
+import {PlatformTest} from "@tsed/common";
+import {Inject} from "@tsed/di";
+import {Job} from "agenda";
+import {AgendaModule} from "./AgendaModule";
+import {Agenda} from "./decorators/agenda";
+import {Define} from "./decorators/define";
+import {Every} from "./decorators/every";
+
+jest.mock("agenda", () => {
+  return {
+    Agenda: class {
+      close = jest.fn();
+      stop = jest.fn();
+      define = jest.fn();
+      every = jest.fn();
+      schedule = jest.fn();
+      now = jest.fn();
+      create = jest.fn().mockReturnValue({
+        repeatEvery: jest.fn().mockReturnThis(),
+        save: jest.fn()
+      });
+      start = jest.fn();
+    }
+  };
+});
+
+@Agenda({namespace: "test-nsp"})
+class CustomCampaign {
+  @Inject()
+  agenda: AgendaModule;
+
+  job: Job;
+
+  $beforeAgendaStart() {
+    this.job = this.agenda.create("customName2", {
+      locale: "fr-FR"
+    });
+  }
+
+  $afterAgendaStart() {
+    return this.job.repeatEvery("1 week").save();
+  }
+
+  @Every("60 seconds")
+  test(job: Job) {
+    // test
+    return "hello " + job.attrs.name;
+  }
+
+  @Define({name: "customName"})
+  test2(job: Job) {
+    // test
+    return "hello " + job.attrs.name;
+  }
+
+  @Define({name: "customName2"})
+  test3() {
+    // test
+  }
+}
+
+@Agenda({namespace: "test-nsp-2"})
+class CustomCampaign2 {
+  @Define({name: "customName"})
+  test(job: Job) {
+    // test
+    return "hello " + job.attrs.name;
+  }
+}
+
+@Agenda({namespace: "test-nsp-3"})
+class CustomCampaign3 {}
+
+describe("AgendaModule", () => {
+  describe("when agenda is enabled", () => {
+    beforeEach(() =>
+      PlatformTest.create({
+        agenda: {
+          enabled: true
+        }
+      })
+    );
+    afterEach(() => PlatformTest.reset());
+
+    describe("$afterListen()", () => {
+      it("should load all jobs", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+        const campaign = PlatformTest.get<CustomCampaign>(CustomCampaign)!;
+
+        await agendaModule.$afterListen();
+
+        expect(agendaModule.agenda.define).toHaveBeenCalledWith("test-nsp.test", {}, expect.any(Function));
+        expect(agendaModule.agenda.every).toHaveBeenCalledWith("60 seconds", "test-nsp.test", {}, {});
+        expect(agendaModule.agenda.start).toHaveBeenCalledWith();
+        expect(agendaModule.agenda.create).toHaveBeenCalledWith("customName2", {locale: "fr-FR"});
+
+        expect(campaign.job.repeatEvery).toHaveBeenCalledWith("1 week");
+        expect(campaign.job.save).toHaveBeenCalledWith();
+
+        const result = await agendaModule.agenda.define.mock.calls[0][2]({
+          attrs: {
+            name: "test-nsp.test"
+          }
+        });
+
+        expect(result).toEqual("hello test-nsp.test");
+      });
+    });
+    describe("schedule()", () => {
+      it("should schedule a job", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+
+        await agendaModule.schedule("now", "test-nsp.test", {});
+
+        expect(agendaModule.agenda.schedule).toHaveBeenCalledWith("now", "test-nsp.test", {});
+      });
+    });
+
+    describe("now()", () => {
+      it("should schedule a job", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+
+        await agendaModule.now("test-nsp.test", {});
+
+        expect(agendaModule.agenda.now).toHaveBeenCalledWith("test-nsp.test", {});
+      });
+    });
+    describe("$onDestroy()", () => {
+      it("should close agenda", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+
+        await agendaModule.$onDestroy();
+
+        expect(agendaModule.agenda.close).toHaveBeenCalledWith({force: true});
+      });
+    });
+  });
+
+  describe("when agenda is enabled but disableJobProcessing = true", () => {
+    beforeEach(() =>
+      PlatformTest.create({
+        agenda: {
+          enabled: true,
+          disableJobProcessing: true
+        }
+      })
+    );
+    afterEach(() => PlatformTest.reset());
+
+    describe("$afterListen()", () => {
+      it("should load all jobs", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+        const campaign = PlatformTest.get<CustomCampaign>(CustomCampaign)!;
+
+        await agendaModule.$afterListen();
+
+        expect(agendaModule.agenda.define).not.toHaveBeenCalled();
+        expect(agendaModule.agenda.every).not.toHaveBeenCalled();
+        expect(agendaModule.agenda.start).toHaveBeenCalledWith();
+        expect(agendaModule.agenda.create).not.toHaveBeenCalled();
+
+        expect(campaign.job).toBeUndefined();
+      });
+    });
+  });
+
+  describe("when agenda is disabled", () => {
+    beforeEach(() =>
+      PlatformTest.create({
+        agenda: {
+          enabled: false
+        }
+      })
+    );
+    afterEach(() => PlatformTest.reset());
+
+    describe("$afterListen()", () => {
+      it("should load all jobs", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+        const campaign = PlatformTest.get<CustomCampaign>(CustomCampaign)!;
+
+        await agendaModule.$afterListen();
+
+        expect(agendaModule.agenda.define).toBeUndefined();
+
+        expect(campaign.job).toBeUndefined();
+      });
+    });
+
+    describe("$onDestroy()", () => {
+      it("should do nothing", async () => {
+        const agendaModule = PlatformTest.get<any>(AgendaModule)!;
+
+        await agendaModule.$onDestroy();
+      });
+    });
+  });
+});

package/src/AgendaModule.ts

@@ -1,6 +1,7 @@
-import {AfterListen, Logger, OnDestroy} from "@tsed/common";
+import {AfterListen, DIContext, Logger, OnDestroy, runInContext} from "@tsed/common";
 import {Constant, Inject, InjectorService, Module, Provider} from "@tsed/di";
-import {Processor} from "agenda";
+import {Job, Processor} from "agenda";
+import {v4 as uuid} from "uuid";
 import {PROVIDER_TYPE_AGENDA} from "./constants/constants";
 import {AgendaStore} from "./interfaces/AgendaStore";
 import {AgendaService} from "./services/AgendaFactory";
@@ -17,18 +18,20 @@ export class AgendaModule implements OnDestroy, AfterListen {
   protected agenda: AgendaService;
 
   @Constant("agenda.enabled", false)
-  private loadAgenda: boolean;
+  private enabled: boolean;
 
   @Constant("agenda.disableJobProcessing", false)
   private disableJobProcessing: boolean;
 
   async $afterListen(): Promise<any> {
-    if (this.loadAgenda) {
+    if (this.enabled) {
       const providers = this.getProviders();
 
       if (!this.disableJobProcessing) {
         this.logger.info("Agenda add definitions...");
         providers.forEach((provider) => this.addAgendaDefinitionsForProvider(provider));
+
+        await this.injector.emit("$beforeAgendaStart");
       }
 
       await this.agenda.start();
@@ -36,6 +39,8 @@ export class AgendaModule implements OnDestroy, AfterListen {
       if (!this.disableJobProcessing) {
         this.logger.info("Agenda add scheduled jobs...");
         await Promise.all(providers.map((provider) => this.scheduleJobsForProvider(provider)));
+
+        await this.injector.emit("$afterAgendaStart");
       }
     } else {
       this.logger.info("Agenda disabled...");
@@ -43,7 +48,7 @@ export class AgendaModule implements OnDestroy, AfterListen {
   }
 
   async $onDestroy(): Promise<any> {
-    if (this.loadAgenda) {
+    if (this.enabled) {
       await this.agenda.stop();
       await this.agenda.close({force: true});
 
@@ -51,6 +56,36 @@ export class AgendaModule implements OnDestroy, AfterListen {
     }
   }
 
+  define(name: string, options?: any, processor?: any) {
+    return this.agenda.define(name, options, (job: Job) => {
+      const $ctx = new DIContext({
+        injector: this.injector,
+        id: uuid(),
+        logger: this.injector.logger
+      });
+
+      $ctx.set("job", job);
+
+      return runInContext($ctx, () => processor(job));
+    });
+  }
+
+  every(interval: string, name: string, data?: any, options?: any) {
+    return this.agenda.every(interval, name, data, options);
+  }
+
+  schedule(when: Date | string, name: string, data?: any) {
+    return this.agenda.schedule(when, name, data);
+  }
+
+  now(name: string, data?: any) {
+    return this.agenda.now(name, data);
+  }
+
+  create(name: string, data?: any) {
+    return this.agenda.create(name, data);
+  }
+
   protected getProviders(): Provider<any>[] {
     return this.injector.getProviders(PROVIDER_TYPE_AGENDA);
   }
@@ -67,7 +102,8 @@ export class AgendaModule implements OnDestroy, AfterListen {
 
       const jobProcessor: Processor = instance[propertyKey].bind(instance) as Processor;
       const jobName = this.getNameForJob(propertyKey, store.namespace, name);
-      this.agenda.define(jobName, options, jobProcessor);
+
+      this.define(jobName, options, jobProcessor);
     });
   }
 
@@ -81,7 +117,7 @@ export class AgendaModule implements OnDestroy, AfterListen {
     const promises = Object.entries(store.every).map(([propertyKey, {interval, name, ...options}]) => {
       const jobName = this.getNameForJob(propertyKey, store.namespace, name);
 
-      return this.agenda.every(interval, jobName, {}, options);
+      return this.every(interval, jobName, {}, options);
     });
 
     await Promise.all(promises);