@wavezync/nestjs-pgboss 5.1.1 → 6.0.0

package/lib/pgboss.service.ts

@@ -52,7 +52,9 @@ export class PgBossService {
     await this.pgBoss.schedule(name, cron, data ?? {}, options ?? {});
     await this.pgBoss.work<TData>(
       name,
-      { ...transformOptions(options), includeMetadata: true },
+      { ...transformOptions(options), includeMetadata: true } as WorkOptions & {
+        includeMetadata: true;
+      },
       handler,
     );
   }

package/lib/utils/handleRetry.ts

@@ -4,24 +4,26 @@ import { mergeMap, retryWhen, delay } from "rxjs/operators";
 export function handleRetry(
   retryAttempts = 9,
   retryDelay = 3000,
-  toRetry: (err: any) => boolean = (_err: any) => true,
+  toRetry: (err: unknown) => boolean = () => true,
 ) {
   return <T>(source: import("rxjs").Observable<T>) =>
     source.pipe(
       retryWhen((attempts) =>
         attempts.pipe(
-          mergeMap((error, index) => {
+          mergeMap((error: unknown, index: number) => {
             const includeError = toRetry(error);
 
             if (includeError) {
               if (index + 1 >= retryAttempts) {
-                return throwError(() => new Error(error.message));
+                const message =
+                  error instanceof Error ? error.message : "Unknown error";
+                return throwError(() => new Error(message));
               }
 
               return of(error).pipe(delay(retryDelay));
             }
 
-            return throwError(() => error);
+            return throwError(() => error as Error);
           }),
         ),
       ),

package/lib/utils/helpers.ts

@@ -1,20 +1,23 @@
 import { WorkOptions, ScheduleOptions } from "pg-boss";
 
-export function transformOptions(options?: WorkOptions | ScheduleOptions) {
+export function transformOptions(
+  options?: WorkOptions | ScheduleOptions,
+): Record<string, unknown> {
   if (!options) return {};
 
-  const transformedOptions: any = { ...options };
+  const transformedOptions: Record<string, unknown> = { ...options };
+  const opts = options as Record<string, unknown>;
 
-  if (typeof (options as any).priority === "number") {
-    transformedOptions.priority = (options as any).priority > 0;
+  if (typeof opts.priority === "number") {
+    transformedOptions.priority = opts.priority > 0;
   }
 
   return transformedOptions;
 }
 
-export function normalizeJob(job: any) {
-  if (typeof job === "object" && "0" in job) {
-    return job[0];
+export function normalizeJob(job: unknown): unknown {
+  if (typeof job === "object" && job !== null && "0" in job) {
+    return (job as Record<string, unknown>)["0"];
   }
   return job;
 }

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@wavezync/nestjs-pgboss",
-  "version": "5.1.1",
+  "version": "6.0.0",
   "description": "A NestJS module that integrates pg-boss for job scheduling and handling.",
   "license": "MIT",
-  "author": "samaratungajs@wavezync.com",
+  "author": "dev@wavezync.com",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "nest build",
-    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format": "prettier --write \"lib/**/*.ts\" \"test/**/*.ts\"",
     "start": "nest start",
     "start:dev": "nest start --watch",
     "start:debug": "nest start --debug --watch",
     "start:prod": "node dist/main",
-    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "lint": "eslint \"{lib,test}/**/*.ts\" --fix",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:cov": "jest --coverage",
@@ -23,7 +23,7 @@
   "peerDependencies": {
     "@nestjs/common": "^11",
     "@nestjs/core": "^11",
-    "pg-boss": "^12",
+    "pg-boss": ">=12.6.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.2.0"
   },
@@ -31,15 +31,14 @@
     "@nestjs/cli": "^11.0.0",
     "@nestjs/schematics": "^11.0.0",
     "@nestjs/testing": "^11.0.0",
-    "@types/express": "^4.17.17",
     "@types/jest": "^29.5.2",
     "@types/node": "^20.3.1",
     "@types/supertest": "^6.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "eslint": "^8.42.0",
-    "eslint-config-prettier": "^9.0.0",
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
     "eslint-plugin-prettier": "^5.0.0",
+    "globals": "^16.0.0",
+    "typescript-eslint": "^8.0.0",
     "jest": "^29.5.0",
     "prettier": "^3.0.0",
     "source-map-support": "^0.5.21",

package/test/decorators.spec.ts

@@ -0,0 +1,82 @@
+import "reflect-metadata";
+import {
+  Job,
+  CronJob,
+  JOB_NAME,
+  JOB_OPTIONS,
+  CRON_EXPRESSION,
+  CRON_OPTIONS,
+  PG_BOSS_JOB_METADATA,
+} from "../lib/decorators/job.decorator";
+
+/* eslint-disable @typescript-eslint/unbound-method */
+describe("Job Decorator", () => {
+  it("should set JOB_NAME, JOB_OPTIONS, and PG_BOSS_JOB_METADATA with defaults", () => {
+    class TestClass {
+      @Job("test-job")
+      handle() {}
+    }
+
+    const method = TestClass.prototype.handle;
+
+    expect(Reflect.getMetadata(JOB_NAME, method)).toBe("test-job");
+    expect(Reflect.getMetadata(JOB_OPTIONS, method)).toEqual({});
+    expect(Reflect.getMetadata(PG_BOSS_JOB_METADATA, method)).toEqual({
+      jobName: "test-job",
+      workOptions: {},
+    });
+  });
+
+  it("should pass custom WorkOptions through", () => {
+    const options = { teamSize: 5, teamConcurrency: 2 } as any;
+
+    class TestClass {
+      @Job("custom-job", options)
+      handle() {}
+    }
+
+    const method = TestClass.prototype.handle;
+
+    expect(Reflect.getMetadata(JOB_OPTIONS, method)).toEqual(options);
+    expect(Reflect.getMetadata(PG_BOSS_JOB_METADATA, method)).toEqual({
+      jobName: "custom-job",
+      workOptions: options,
+    });
+  });
+});
+
+describe("CronJob Decorator", () => {
+  it("should set JOB_NAME, CRON_EXPRESSION, CRON_OPTIONS, and PG_BOSS_JOB_METADATA with defaults", () => {
+    class TestClass {
+      @CronJob("cron-job", "* * * * *")
+      handle() {}
+    }
+
+    const method = TestClass.prototype.handle;
+
+    expect(Reflect.getMetadata(JOB_NAME, method)).toBe("cron-job");
+    expect(Reflect.getMetadata(CRON_EXPRESSION, method)).toBe("* * * * *");
+    expect(Reflect.getMetadata(CRON_OPTIONS, method)).toEqual({});
+    expect(Reflect.getMetadata(PG_BOSS_JOB_METADATA, method)).toEqual({
+      jobName: "cron-job",
+      workOptions: {},
+    });
+  });
+
+  it("should pass custom ScheduleOptions through", () => {
+    const options = { tz: "America/New_York" };
+
+    class TestClass {
+      @CronJob("cron-custom", "0 9 * * *", options)
+      handle() {}
+    }
+
+    const method = TestClass.prototype.handle;
+
+    expect(Reflect.getMetadata(CRON_OPTIONS, method)).toEqual(options);
+    expect(Reflect.getMetadata(PG_BOSS_JOB_METADATA, method)).toEqual({
+      jobName: "cron-custom",
+      workOptions: options,
+    });
+  });
+});

package/test/handleRetry.spec.ts

@@ -0,0 +1,69 @@
+import { Observable, of, lastValueFrom } from "rxjs";
+import { handleRetry } from "../lib/utils/handleRetry";
+
+describe("handleRetry", () => {
+  it("should pass through successful values without retrying", async () => {
+    const result = await lastValueFrom(of("success").pipe(handleRetry()));
+    expect(result).toBe("success");
+  });
+
+  it("should retry on error and eventually succeed", async () => {
+    let attempt = 0;
+    const source$ = new Observable<string>((subscriber) => {
+      attempt++;
+      if (attempt < 3) {
+        subscriber.error(new Error("fail"));
+      } else {
+        subscriber.next("success");
+        subscriber.complete();
+      }
+    });
+
+    const result = await lastValueFrom(source$.pipe(handleRetry(5, 1)));
+    expect(result).toBe("success");
+    expect(attempt).toBe(3);
+  });
+
+  it("should throw after exhausting retry attempts", async () => {
+    const source$ = new Observable<string>((subscriber) => {
+      subscriber.error(new Error("persistent failure"));
+    });
+
+    await expect(
+      lastValueFrom(source$.pipe(handleRetry(3, 1))),
+    ).rejects.toThrow("persistent failure");
+  });
+
+  it("should respect custom retryAttempts count", async () => {
+    let attempts = 0;
+    const source$ = new Observable<string>((subscriber) => {
+      attempts++;
+      subscriber.error(new Error("fail"));
+    });
+
+    await expect(
+      lastValueFrom(source$.pipe(handleRetry(2, 1))),
+    ).rejects.toThrow("fail");
+    expect(attempts).toBe(2);
+  });
+
+  it("should throw immediately when toRetry predicate returns false", async () => {
+    const source$ = new Observable<string>((subscriber) => {
+      subscriber.error(new Error("not retryable"));
+    });
+
+    await expect(
+      lastValueFrom(source$.pipe(handleRetry(5, 1, () => false))),
+    ).rejects.toThrow("not retryable");
+  });
+
+  it('should use "Unknown error" for non-Error throws', async () => {
+    const source$ = new Observable<string>((subscriber) => {
+      subscriber.error("string error");
+    });
+
+    await expect(
+      lastValueFrom(source$.pipe(handleRetry(1, 1))),
+    ).rejects.toThrow("Unknown error");
+  });
+});

package/test/handler-scanner.service.spec.ts

@@ -1,82 +1,283 @@
-jest.mock("pg-boss", () => ({}));
+jest.mock("pg-boss", () => {
+  return {
+    PgBoss: jest.fn().mockImplementation(() => ({
+      on: jest.fn(),
+      start: jest.fn(),
+      stop: jest.fn(),
+      send: jest.fn(),
+      schedule: jest.fn(),
+      work: jest.fn(),
+      createQueue: jest.fn(),
+    })),
+  };
+});
 
 import { Test, TestingModule } from "@nestjs/testing";
 import { Reflector, ModulesContainer } from "@nestjs/core";
 import { HandlerScannerService } from "../lib/handler-scanner.service";
 import { PgBossService } from "../lib/pgboss.service";
-import { JOB_NAME, JOB_OPTIONS } from "../lib/decorators/job.decorator";
+import {
+  JOB_NAME,
+  JOB_OPTIONS,
+  CRON_EXPRESSION,
+  CRON_OPTIONS,
+} from "../lib/decorators/job.decorator";
 
 describe("HandlerScannerService", () => {
-  let service: HandlerScannerService;
-  let mockPgBossService: any;
-  let mockReflector: any;
-  let mockModulesContainer: Map<string, any>;
-
-  class TestHandler {
-    handle() {}
-  }
+  let scanner: HandlerScannerService;
+  let pgBossService: jest.Mocked<
+    Pick<PgBossService, "registerJob" | "registerCronJob">
+  >;
+  let reflector: Reflector;
+  let modulesContainer: ModulesContainer;
 
   beforeEach(async () => {
-    mockPgBossService = {
+    pgBossService = {
       registerJob: jest.fn().mockResolvedValue(undefined),
       registerCronJob: jest.fn().mockResolvedValue(undefined),
     };
 
-    mockReflector = { get: jest.fn() };
-    mockModulesContainer = new Map();
-
     const module: TestingModule = await Test.createTestingModule({
       providers: [
         HandlerScannerService,
-        { provide: PgBossService, useValue: mockPgBossService },
-        { provide: Reflector, useValue: mockReflector },
-        { provide: ModulesContainer, useValue: mockModulesContainer },
+        { provide: PgBossService, useValue: pgBossService },
+        Reflector,
+        { provide: ModulesContainer, useValue: new Map() },
       ],
     }).compile();
 
-    service = module.get<HandlerScannerService>(HandlerScannerService);
+    scanner = module.get<HandlerScannerService>(HandlerScannerService);
+    reflector = module.get<Reflector>(Reflector);
+    modulesContainer = module.get<ModulesContainer>(ModulesContainer);
   });
 
-  afterEach(() => {
-    jest.clearAllMocks();
+  it("should be defined", () => {
+    expect(scanner).toBeDefined();
   });
 
-  describe("teamSize", () => {
-    const setupHandler = (jobOptions?: { teamSize?: number }) => {
-      const instance = new TestHandler();
-      mockModulesContainer.set("TestModule", {
-        providers: new Map([["TestHandler", { instance }]]),
-      });
-      mockReflector.get.mockImplementation((key: string, target: any) => {
-        if (key === JOB_NAME && target === instance.handle) return "my-job";
-        if (key === JOB_OPTIONS && target === instance.handle)
-          return jobOptions;
-        return undefined;
-      });
+  it("should register @Job-decorated methods via registerJob", async () => {
+    const handler = jest.fn();
+    const instance = {
+      handle: handler,
     };
+    Object.setPrototypeOf(
+      instance,
+      Object.create(null, {
+        constructor: { value: class {} },
+        handle: { value: handler, enumerable: true },
+      }),
+    );
 
-    it("should register job once by default", async () => {
-      setupHandler();
-      await service.scanAndRegisterHandlers();
-      expect(mockPgBossService.registerJob).toHaveBeenCalledTimes(1);
+    const reflectorGetSpy = jest.spyOn(reflector, "get");
+    reflectorGetSpy.mockImplementation((key: any, target: any) => {
+      if (target === handler) {
+        if (key === JOB_NAME) return "test-job";
+        if (key === JOB_OPTIONS) return { teamSize: 2 };
+      }
+      return undefined;
     });
 
-    it("should register job multiple times when teamSize > 1", async () => {
-      setupHandler({ teamSize: 3 });
-      await service.scanAndRegisterHandlers();
-      expect(mockPgBossService.registerJob).toHaveBeenCalledTimes(3);
+    const fakeModule = {
+      providers: new Map([
+        [
+          "TestProvider",
+          {
+            instance,
+            metatype: class {},
+          },
+        ],
+      ]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    await scanner.scanAndRegisterHandlers();
+
+    expect(pgBossService.registerJob).toHaveBeenCalledWith(
+      "test-job",
+      expect.any(Function),
+      { teamSize: 2 },
+    );
+  });
+
+  it("should register @CronJob-decorated methods via registerCronJob", async () => {
+    const handler = jest.fn();
+    const instance = {
+      handle: handler,
+    };
+    Object.setPrototypeOf(
+      instance,
+      Object.create(null, {
+        constructor: { value: class {} },
+        handle: { value: handler, enumerable: true },
+      }),
+    );
+
+    const reflectorGetSpy = jest.spyOn(reflector, "get");
+    reflectorGetSpy.mockImplementation((key: any, target: any) => {
+      if (target === handler) {
+        if (key === JOB_NAME) return "cron-job";
+        if (key === CRON_EXPRESSION) return "* * * * *";
+        if (key === CRON_OPTIONS) return { tz: "UTC" };
+      }
+      return undefined;
+    });
+
+    const fakeModule = {
+      providers: new Map([
+        [
+          "TestProvider",
+          {
+            instance,
+            metatype: class {},
+          },
+        ],
+      ]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    await scanner.scanAndRegisterHandlers();
+
+    expect(pgBossService.registerCronJob).toHaveBeenCalledWith(
+      "cron-job",
+      "* * * * *",
+      expect.any(Function),
+      {},
+      { tz: "UTC" },
+    );
+  });
+
+  it("should skip providers with no instance", async () => {
+    const fakeModule = {
+      providers: new Map([
+        ["NullProvider", { instance: null, metatype: class {} }],
+      ]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    await scanner.scanAndRegisterHandlers();
+
+    expect(pgBossService.registerJob).not.toHaveBeenCalled();
+    expect(pgBossService.registerCronJob).not.toHaveBeenCalled();
+  });
+
+  it("should skip methods without job metadata", async () => {
+    const instance = {
+      someMethod: jest.fn(),
+    };
+    Object.setPrototypeOf(
+      instance,
+      Object.create(null, {
+        constructor: { value: class {} },
+        someMethod: { value: jest.fn(), enumerable: true },
+      }),
+    );
+
+    jest.spyOn(reflector, "get").mockReturnValue(undefined);
+
+    const fakeModule = {
+      providers: new Map([["TestProvider", { instance, metatype: class {} }]]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    await scanner.scanAndRegisterHandlers();
+
+    expect(pgBossService.registerJob).not.toHaveBeenCalled();
+    expect(pgBossService.registerCronJob).not.toHaveBeenCalled();
+  });
+
+  it("should log errors when registration fails", async () => {
+    const handler = jest.fn();
+    const instance = {
+      handle: handler,
+    };
+    Object.setPrototypeOf(
+      instance,
+      Object.create(null, {
+        constructor: { value: class {} },
+        handle: { value: handler, enumerable: true },
+      }),
+    );
+
+    jest.spyOn(reflector, "get").mockImplementation((key: any, target: any) => {
+      if (target === handler) {
+        if (key === JOB_NAME) return "failing-job";
+        if (key === JOB_OPTIONS) return {};
+      }
+      return undefined;
     });
 
-    it("should default to 1 when teamSize is 0", async () => {
-      setupHandler({ teamSize: 0 });
-      await service.scanAndRegisterHandlers();
-      expect(mockPgBossService.registerJob).toHaveBeenCalledTimes(1);
+    pgBossService.registerJob.mockRejectedValue(
+      new Error("registration failed"),
+    );
+
+    const fakeModule = {
+      providers: new Map([["TestProvider", { instance, metatype: class {} }]]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    // Should not throw
+    await expect(scanner.scanAndRegisterHandlers()).resolves.not.toThrow();
+  });
+
+  it("should bind handler to the correct instance context", async () => {
+    const handler = jest.fn();
+    const instance = {
+      handle: handler,
+    };
+    Object.setPrototypeOf(
+      instance,
+      Object.create(null, {
+        constructor: { value: class {} },
+        handle: { value: handler, enumerable: true },
+      }),
+    );
+
+    jest.spyOn(reflector, "get").mockImplementation((key: any, target: any) => {
+      if (target === handler) {
+        if (key === JOB_NAME) return "bound-job";
+        if (key === JOB_OPTIONS) return {};
+      }
+      return undefined;
     });
 
-    it("should default to 1 when teamSize is negative", async () => {
-      setupHandler({ teamSize: -5 });
-      await service.scanAndRegisterHandlers();
-      expect(mockPgBossService.registerJob).toHaveBeenCalledTimes(1);
+    const fakeModule = {
+      providers: new Map([["TestProvider", { instance, metatype: class {} }]]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    await scanner.scanAndRegisterHandlers();
+
+    // The handler passed to registerJob should be bound to the instance
+    const boundHandler = pgBossService.registerJob.mock.calls[0][1];
+    expect(typeof boundHandler).toBe("function");
+  });
+
+  it("should skip prototype getters that throw (e.g. TypeORM DataSource.mongoManager)", async () => {
+    const proto = Object.create(null);
+    Object.defineProperty(proto, "constructor", { value: class {} });
+    Object.defineProperty(proto, "mongoManager", {
+      get() {
+        throw new Error(
+          "MongoEntityManager is only available for MongoDB databases.",
+        );
+      },
+      enumerable: true,
     });
+    Object.defineProperty(proto, "handle", {
+      value: jest.fn(),
+      enumerable: true,
+    });
+
+    const instance = Object.create(proto);
+
+    jest.spyOn(reflector, "get").mockReturnValue(undefined);
+
+    const fakeModule = {
+      providers: new Map([["TestProvider", { instance, metatype: class {} }]]),
+    };
+    (modulesContainer as Map<string, any>).set("TestModule", fakeModule);
+
+    // Should not throw despite the getter
+    await expect(scanner.scanAndRegisterHandlers()).resolves.not.toThrow();
   });
 });

package/test/helpers.spec.ts

@@ -0,0 +1,47 @@
+import { transformOptions, normalizeJob } from "../lib/utils/helpers";
+
+describe("transformOptions", () => {
+  it("should return {} when options is undefined", () => {
+    expect(transformOptions(undefined)).toEqual({});
+  });
+
+  it("should spread options through unchanged when no priority", () => {
+    const options = { tz: "UTC" };
+    expect(transformOptions(options)).toEqual({ tz: "UTC" });
+  });
+
+  it("should convert numeric priority > 0 to true", () => {
+    const options = { priority: 5 } as any;
+    expect(transformOptions(options)).toEqual({ priority: true });
+  });
+
+  it("should convert numeric priority <= 0 to false", () => {
+    expect(transformOptions({ priority: 0 } as any)).toEqual({
+      priority: false,
+    });
+    expect(transformOptions({ priority: -1 } as any)).toEqual({
+      priority: false,
+    });
+  });
+});
+
+describe("normalizeJob", () => {
+  it('should return the "0" property from array-like objects', () => {
+    const job = { "0": { id: "job-1", data: {} } };
+    expect(normalizeJob(job)).toEqual({ id: "job-1", data: {} });
+  });
+
+  it("should return the job as-is for plain objects", () => {
+    const job = { id: "job-1", data: {} };
+    expect(normalizeJob(job)).toEqual({ id: "job-1", data: {} });
+  });
+
+  it("should return primitives unchanged", () => {
+    expect(normalizeJob("test")).toBe("test");
+    expect(normalizeJob(42)).toBe(42);
+  });
+
+  it("should handle null input", () => {
+    expect(normalizeJob(null)).toBeNull();
+  });
+});