@pikku/queue-pg-boss 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.12.0
+
+### New Features
+
+- `setServices()`, `start()`, `stop()` lifecycle methods on scheduler and queue workers
+
 ## 0.11.0
 
 ## 0.11.2
@@ -8,8 +14,6 @@
 - Updated dependencies [db9c7bf]
   - @pikku/core@0.11.2
 
-## 0.11.2
-
 ### Fixes
 
 - ddd87eaf: Simplify CreateWireServices type signature for custom Config compatibility

package/dist/pg-boss-queue-worker.d.ts

@@ -1,14 +1,12 @@
 import { PgBoss, type WorkOptions } from 'pg-boss';
-import type { QueueWorkers, PikkuWorkerConfig, QueueConfigMapping, ConfigValidationResult } from '@pikku/core/queue';
-import { CoreSingletonServices, CreateWireServices } from '@pikku/core';
+import type { QueueWorkers, PikkuWorkerConfig, QueueConfigMapping, ConfigValidationResult, QueueJob } from '@pikku/core/queue';
+import type { Logger } from '@pikku/core/services';
 export declare const mapPikkuWorkerToPgBoss: (workerConfig?: PikkuWorkerConfig) => WorkOptions;
 /**
  * pg-boss/PostgreSQL queue worker implementation
  * Supports job results, retries, and PostgreSQL-based queuing
  */
 export declare class PgBossQueueWorkers implements QueueWorkers {
-    private singletonServices;
-    private createWireServices?;
     readonly name = "pg-boss";
     readonly supportsResults = true;
     /**
@@ -18,7 +16,13 @@ export declare class PgBossQueueWorkers implements QueueWorkers {
     readonly configMappings: QueueConfigMapping;
     private pgBoss;
     private activeWorkers;
-    constructor(pgBoss: PgBoss, singletonServices: CoreSingletonServices, createWireServices?: CreateWireServices | undefined);
+    private runJob?;
+    private logger?;
+    constructor(pgBoss: PgBoss);
+    setJobRunner(runJob: (params: {
+        job: QueueJob;
+        updateProgress?: (progress: number | string | object) => Promise<void>;
+    }) => Promise<void>, logger: Logger): void;
     /**
      * Scan state and register all compatible processors
      */

package/dist/pg-boss-queue-worker.js

@@ -1,4 +1,4 @@
-import { runQueueJob, registerQueueWorkers, QueueJobFailedError, QueueJobDiscardedError, } from '@pikku/core/queue';
+import { registerQueueWorkers, QueueJobFailedError, QueueJobDiscardedError, } from '@pikku/core/queue';
 import { mapPgBossJobToQueueJob } from './utils.js';
 export const mapPikkuWorkerToPgBoss = (workerConfig) => {
     const workerOptions = {
@@ -17,8 +17,6 @@ export const mapPikkuWorkerToPgBoss = (workerConfig) => {
  * Supports job results, retries, and PostgreSQL-based queuing
  */
 export class PgBossQueueWorkers {
-    singletonServices;
-    createWireServices;
     name = 'pg-boss';
     supportsResults = true;
     /**
@@ -85,34 +83,36 @@ export class PgBossQueueWorkers {
     };
     pgBoss;
     activeWorkers = new Map();
-    constructor(pgBoss, singletonServices, createWireServices) {
-        this.singletonServices = singletonServices;
-        this.createWireServices = createWireServices;
+    runJob;
+    logger;
+    constructor(pgBoss) {
         this.pgBoss = pgBoss;
     }
+    setJobRunner(runJob, logger) {
+        this.runJob = runJob;
+        this.logger = logger;
+    }
     /**
      * Scan state and register all compatible processors
      */
     async registerQueues() {
-        return await registerQueueWorkers(this.configMappings, this.singletonServices.logger, async (queueName, processor) => {
+        if (!this.runJob || !this.logger) {
+            throw new Error('PgBossQueueWorkers requires setJobRunner() before registerQueues()');
+        }
+        return await registerQueueWorkers(this.configMappings, this.logger, async (queueName, processor) => {
             await this.pgBoss.createQueue(queueName);
-            const workerId = await this.pgBoss.work(processor.queueName, {
+            const workerId = await this.pgBoss.work(processor.name, {
                 ...mapPikkuWorkerToPgBoss(processor.config),
                 includeMetadata: true,
             }, async (jobs) => {
-                if (!this.singletonServices) {
-                    throw new Error('Singleton services not available');
-                }
                 if (!jobs || jobs.length === 0) {
-                    this.singletonServices.logger.warn(`No jobs received for queue ${queueName}`);
+                    this.logger.warn(`No jobs received for queue ${queueName}`);
                     return;
                 }
                 // Process all jobs in parallel
                 await Promise.all(jobs.map(async (job) => {
                     try {
-                        await runQueueJob({
-                            singletonServices: this.singletonServices,
-                            createWireServices: this.createWireServices,
+                        await this.runJob({
                             job: mapPgBossJobToQueueJob(job, this.pgBoss),
                         });
                     }
@@ -125,7 +125,7 @@ export class PgBossQueueWorkers {
                         }
                         else if (error instanceof QueueJobDiscardedError) {
                             // For pg-boss, complete the job successfully to discard it
-                            this.singletonServices.logger.info(`PgBoss job ${job.id} discarded: ${error.message}`);
+                            this.logger.info(`PgBoss job ${job.id} discarded: ${error.message}`);
                             await this.pgBoss.complete(queueName, job.id);
                         }
                         else {

package/dist/pg-boss-scheduler-service.d.ts

@@ -1,12 +1,21 @@
 import { PgBoss } from 'pg-boss';
-import { SchedulerService, ScheduledTaskInfo, ScheduledTaskSummary, CoreUserSession } from '@pikku/core';
+import { SchedulerService, SchedulerRuntimeHandlers, ScheduledTaskInfo, ScheduledTaskSummary, CoreUserSession } from '@pikku/core';
 /**
  * pg-boss scheduler service implementation
- * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL
+ * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
+ * Handles both one-off delayed RPCs and recurring cron-scheduled tasks.
  */
 export declare class PgBossSchedulerService extends SchedulerService {
     private pgBoss;
+    private scheduledCronNames;
+    private handlers?;
     constructor(pgBoss: PgBoss);
+    /**
+     * Set services needed for processing recurring tasks.
+     * Must be called before start() since the scheduler is typically
+     * created before singletonServices are available.
+     */
+    setServices(handlers: SchedulerRuntimeHandlers): void;
     /**
      * Initialize - no-op as pg-boss is already initialized by factory
      */
@@ -32,4 +41,13 @@ export declare class PgBossSchedulerService extends SchedulerService {
      * Close - no-op as pg-boss lifecycle is managed by factory
      */
     close(): Promise<void>;
+    /**
+     * Start recurring scheduled tasks.
+     * Registers a pg-boss worker to process recurring jobs via runScheduledTask.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop recurring scheduled tasks by unscheduling them from pg-boss.
+     */
+    stop(): Promise<void>;
 }

package/dist/pg-boss-scheduler-service.js

@@ -1,14 +1,26 @@
 import { SchedulerService, parseDurationString, } from '@pikku/core';
+import { getScheduledTasks } from '@pikku/core/scheduler';
 /**
  * pg-boss scheduler service implementation
- * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL
+ * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
+ * Handles both one-off delayed RPCs and recurring cron-scheduled tasks.
  */
 export class PgBossSchedulerService extends SchedulerService {
     pgBoss;
+    scheduledCronNames = [];
+    handlers;
     constructor(pgBoss) {
         super();
         this.pgBoss = pgBoss;
     }
+    /**
+     * Set services needed for processing recurring tasks.
+     * Must be called before start() since the scheduler is typically
+     * created before singletonServices are available.
+     */
+    setServices(handlers) {
+        this.handlers = handlers;
+    }
     /**
      * Initialize - no-op as pg-boss is already initialized by factory
      */
@@ -77,4 +89,38 @@ export class PgBossSchedulerService extends SchedulerService {
     async close() {
         // No-op - pg-boss lifecycle is managed by factory
     }
+    /**
+     * Start recurring scheduled tasks.
+     * Registers a pg-boss worker to process recurring jobs via runScheduledTask.
+     */
+    async start() {
+        if (!this.handlers) {
+            throw new Error('PgBossSchedulerService requires setServices() before start()');
+        }
+        const scheduledTasks = getScheduledTasks();
+        for (const [name, task] of scheduledTasks) {
+            const cronName = `pikku-recurring-scheduled-task:${name}`;
+            await this.pgBoss.schedule(cronName, task.schedule, {
+                rpcName: name,
+            });
+            this.scheduledCronNames.push(cronName);
+            // Register a worker to process the scheduled jobs
+            await this.pgBoss.work(cronName, async (jobs) => {
+                for (const job of jobs) {
+                    const { rpcName } = job.data;
+                    this.handlers.logger.info(`Running scheduled task: ${rpcName}`);
+                    await this.handlers.runScheduledTask(rpcName);
+                }
+            });
+        }
+    }
+    /**
+     * Stop recurring scheduled tasks by unscheduling them from pg-boss.
+     */
+    async stop() {
+        for (const cronName of this.scheduledCronNames) {
+            await this.pgBoss.unschedule(cronName);
+        }
+        this.scheduledCronNames = [];
+    }
 }

package/dist/pg-boss-service-factory.d.ts

@@ -30,6 +30,7 @@ export declare class PgBossServiceFactory {
      * Get the scheduler service for managing recurring tasks
      */
     getSchedulerService(): PgBossSchedulerService;
+    setSchedulerRuntime(singletonServices: CoreSingletonServices, createWireServices?: CreateWireServices): void;
     /**
      * Close all services and the pg-boss connection
      */

package/dist/pg-boss-service-factory.js

@@ -2,6 +2,8 @@ import { PgBoss } from 'pg-boss';
 import { PgBossQueueService } from './pg-boss-queue-service.js';
 import { PgBossQueueWorkers } from './pg-boss-queue-worker.js';
 import { PgBossSchedulerService } from './pg-boss-scheduler-service.js';
+import { createQueueJobRunner } from '@pikku/core/queue';
+import { createSchedulerRuntimeHandlers } from '@pikku/core/scheduler';
 /**
  * Factory class for pg-boss services
  * Manages a single PgBoss instance shared across queue, worker, and scheduler services
@@ -46,8 +48,9 @@ export class PgBossServiceFactory {
      */
     getQueueWorkers(singletonServices, createWireServices) {
         if (!this.queueWorkers) {
-            this.queueWorkers = new PgBossQueueWorkers(this.pgBoss, singletonServices, createWireServices);
+            this.queueWorkers = new PgBossQueueWorkers(this.pgBoss);
         }
+        this.queueWorkers.setJobRunner(createQueueJobRunner({ singletonServices, createWireServices }), singletonServices.logger);
         return this.queueWorkers;
     }
     /**
@@ -59,6 +62,12 @@ export class PgBossServiceFactory {
         }
         return this.schedulerService;
     }
+    setSchedulerRuntime(singletonServices, createWireServices) {
+        this.getSchedulerService().setServices(createSchedulerRuntimeHandlers({
+            singletonServices,
+            createWireServices,
+        }));
+    }
     /**
      * Close all services and the pg-boss connection
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/queue-pg-boss",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -13,10 +13,10 @@
     "release": "npm run build && npm test"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.11.2"
+    "@pikku/core": "^0.12.0"
   },
   "dependencies": {
-    "pg-boss": "^12.2.0"
+    "pg-boss": "^12.9.0"
   },
   "devDependencies": {
     "typescript": "^5.9"

package/src/pg-boss-queue-worker.test.ts

@@ -0,0 +1,15 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
+
+describe('PgBossQueueWorkers', () => {
+  test('requires setJobRunner before registerQueues', async () => {
+    const workers = new PgBossQueueWorkers({} as any)
+
+    await assert.rejects(() => workers.registerQueues(), {
+      message:
+        'PgBossQueueWorkers requires setJobRunner() before registerQueues()',
+    })
+  })
+})

package/src/pg-boss-queue-worker.ts

@@ -4,14 +4,14 @@ import type {
   PikkuWorkerConfig,
   QueueConfigMapping,
   ConfigValidationResult,
+  QueueJob,
 } from '@pikku/core/queue'
 import {
-  runQueueJob,
   registerQueueWorkers,
   QueueJobFailedError,
   QueueJobDiscardedError,
 } from '@pikku/core/queue'
-import { CoreSingletonServices, CreateWireServices } from '@pikku/core'
+import type { Logger } from '@pikku/core/services'
 import { mapPgBossJobToQueueJob } from './utils.js'
 
 export const mapPikkuWorkerToPgBoss = (
@@ -120,47 +120,60 @@ export class PgBossQueueWorkers implements QueueWorkers {
 
   private pgBoss: PgBoss
   private activeWorkers = new Map<string, string>()
+  private runJob?:
+    | ((params: {
+        job: QueueJob
+        updateProgress?: (progress: number | string | object) => Promise<void>
+      }) => Promise<void>)
+    | undefined
+  private logger?: Logger
 
-  constructor(
-    pgBoss: PgBoss,
-    private singletonServices: CoreSingletonServices,
-    private createWireServices?: CreateWireServices
-  ) {
+  constructor(pgBoss: PgBoss) {
     this.pgBoss = pgBoss
   }
 
+  setJobRunner(
+    runJob: (params: {
+      job: QueueJob
+      updateProgress?: (progress: number | string | object) => Promise<void>
+    }) => Promise<void>,
+    logger: Logger
+  ): void {
+    this.runJob = runJob
+    this.logger = logger
+  }
+
   /**
    * Scan state and register all compatible processors
    */
   async registerQueues(): Promise<Record<string, ConfigValidationResult[]>> {
+    if (!this.runJob || !this.logger) {
+      throw new Error(
+        'PgBossQueueWorkers requires setJobRunner() before registerQueues()'
+      )
+    }
+
     return await registerQueueWorkers(
       this.configMappings,
-      this.singletonServices.logger,
+      this.logger,
       async (queueName, processor) => {
         await this.pgBoss.createQueue(queueName)
         const workerId = await this.pgBoss.work<any>(
-          processor.queueName,
+          processor.name,
           {
             ...mapPikkuWorkerToPgBoss(processor.config),
             includeMetadata: true,
           },
           async (jobs) => {
-            if (!this.singletonServices) {
-              throw new Error('Singleton services not available')
-            }
             if (!jobs || jobs.length === 0) {
-              this.singletonServices.logger.warn(
-                `No jobs received for queue ${queueName}`
-              )
+              this.logger!.warn(`No jobs received for queue ${queueName}`)
               return
             }
             // Process all jobs in parallel
             await Promise.all(
               jobs.map(async (job) => {
                 try {
-                  await runQueueJob({
-                    singletonServices: this.singletonServices,
-                    createWireServices: this.createWireServices,
+                  await this.runJob!({
                     job: mapPgBossJobToQueueJob(job, this.pgBoss),
                   })
                 } catch (error: unknown) {
@@ -171,7 +184,7 @@ export class PgBossQueueWorkers implements QueueWorkers {
                     })
                   } else if (error instanceof QueueJobDiscardedError) {
                     // For pg-boss, complete the job successfully to discard it
-                    this.singletonServices.logger.info(
+                    this.logger!.info(
                       `PgBoss job ${job.id} discarded: ${error.message}`
                     )
                     await this.pgBoss.complete(queueName, job.id)

package/src/pg-boss-scheduler-service.ts

@@ -1,11 +1,13 @@
 import { PgBoss } from 'pg-boss'
 import {
   SchedulerService,
+  SchedulerRuntimeHandlers,
   ScheduledTaskInfo,
   ScheduledTaskSummary,
   CoreUserSession,
   parseDurationString,
 } from '@pikku/core'
+import { getScheduledTasks } from '@pikku/core/scheduler'
 
 /**
  * Data stored in scheduled job
@@ -18,13 +20,26 @@ interface ScheduledJobData {
 
 /**
  * pg-boss scheduler service implementation
- * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL
+ * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
+ * Handles both one-off delayed RPCs and recurring cron-scheduled tasks.
  */
 export class PgBossSchedulerService extends SchedulerService {
+  private scheduledCronNames: string[] = []
+  private handlers?: SchedulerRuntimeHandlers
+
   constructor(private pgBoss: PgBoss) {
     super()
   }
 
+  /**
+   * Set services needed for processing recurring tasks.
+   * Must be called before start() since the scheduler is typically
+   * created before singletonServices are available.
+   */
+  setServices(handlers: SchedulerRuntimeHandlers): void {
+    this.handlers = handlers
+  }
+
   /**
    * Initialize - no-op as pg-boss is already initialized by factory
    */
@@ -118,4 +133,45 @@ export class PgBossSchedulerService extends SchedulerService {
   async close(): Promise<void> {
     // No-op - pg-boss lifecycle is managed by factory
   }
+
+  /**
+   * Start recurring scheduled tasks.
+   * Registers a pg-boss worker to process recurring jobs via runScheduledTask.
+   */
+  async start(): Promise<void> {
+    if (!this.handlers) {
+      throw new Error(
+        'PgBossSchedulerService requires setServices() before start()'
+      )
+    }
+
+    const scheduledTasks = getScheduledTasks()
+
+    for (const [name, task] of scheduledTasks) {
+      const cronName = `pikku-recurring-scheduled-task:${name}`
+      await this.pgBoss.schedule(cronName, task.schedule, {
+        rpcName: name,
+      } as ScheduledJobData)
+      this.scheduledCronNames.push(cronName)
+
+      // Register a worker to process the scheduled jobs
+      await this.pgBoss.work<ScheduledJobData>(cronName, async (jobs) => {
+        for (const job of jobs) {
+          const { rpcName } = job.data
+          this.handlers!.logger.info(`Running scheduled task: ${rpcName}`)
+          await this.handlers!.runScheduledTask(rpcName)
+        }
+      })
+    }
+  }
+
+  /**
+   * Stop recurring scheduled tasks by unscheduling them from pg-boss.
+   */
+  async stop(): Promise<void> {
+    for (const cronName of this.scheduledCronNames) {
+      await this.pgBoss.unschedule(cronName)
+    }
+    this.scheduledCronNames = []
+  }
 }

package/src/pg-boss-service-factory.ts

@@ -3,6 +3,8 @@ import { PgBossQueueService } from './pg-boss-queue-service.js'
 import { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
 import { PgBossSchedulerService } from './pg-boss-scheduler-service.js'
 import type { CoreSingletonServices, CreateWireServices } from '@pikku/core'
+import { createQueueJobRunner } from '@pikku/core/queue'
+import { createSchedulerRuntimeHandlers } from '@pikku/core/scheduler'
 
 /**
  * Factory class for pg-boss services
@@ -55,12 +57,12 @@ export class PgBossServiceFactory {
     createWireServices?: CreateWireServices
   ): PgBossQueueWorkers {
     if (!this.queueWorkers) {
-      this.queueWorkers = new PgBossQueueWorkers(
-        this.pgBoss,
-        singletonServices,
-        createWireServices
-      )
+      this.queueWorkers = new PgBossQueueWorkers(this.pgBoss)
     }
+    this.queueWorkers.setJobRunner(
+      createQueueJobRunner({ singletonServices, createWireServices }),
+      singletonServices.logger
+    )
     return this.queueWorkers
   }
 
@@ -74,6 +76,18 @@ export class PgBossServiceFactory {
     return this.schedulerService
   }
 
+  setSchedulerRuntime(
+    singletonServices: CoreSingletonServices,
+    createWireServices?: CreateWireServices
+  ): void {
+    this.getSchedulerService().setServices(
+      createSchedulerRuntimeHandlers({
+        singletonServices,
+        createWireServices,
+      })
+    )
+  }
+
   /**
    * Close all services and the pg-boss connection
    */