nestjs-pg-boss 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbderraHman El Haddad Asofi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# nestjs-pg-boss
+
+A NestJS module for [pg-boss](https://github.com/timgit/pg-boss) (v12). Queues are declared in code, workers are decorated methods, and the instance follows the Nest lifecycle.
+
+Works with NestJS 10+ and pg-boss 12. Requires Node 22.12 or newer.
+
+```bash
+npm i nestjs-pg-boss pg-boss
+```
+
+The package is ESM-only, because pg-boss 12 is. A CommonJS Nest app (the default for `nest new` before v12) can still `import` from it: Node 22.12+ loads ESM from `require()` without a flag. That is also why the Node floor is 22.12, which is pg-boss 12's own minimum.
+
+## Setup
+
+```ts
+@Module({
+  imports: [
+    PgBossModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        connectionString: config.getOrThrow('DATABASE_URL'),
+        schema: 'pgboss',
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`forRoot` takes every option `new PgBoss()` does, plus:
+
+| Option | Default | |
+| --- | --- | --- |
+| `start` | | Passed to `boss.start()`, e.g. `{ attempts: 5 }`. |
+| `stop` | `{ graceful: true, timeout: 30000 }` | Passed to `boss.stop()` on shutdown. |
+| `registerWorkers` | `true` | Set `false` in processes that only enqueue. |
+
+Call `app.enableShutdownHooks()` in `main.ts` so SIGTERM lets running jobs finish.
+
+## Declare a queue and enqueue
+
+```ts
+@Module({
+  imports: [PgBossModule.registerQueue({ name: 'email', retryLimit: 3, retryBackoff: true, deadLetter: 'email-dead' }, 'email-dead')],
+  providers: [Mailer, EmailProcessor],
+})
+export class EmailModule {}
+
+@Injectable()
+export class Mailer {
+  constructor(@InjectQueue('email') private readonly queue: JobQueue<SendEmail>) {}
+
+  send(payload: SendEmail) {
+    return this.queue.send(payload);
+  }
+}
+```
+
+The queue is created on boot. If it already exists, the options pg-boss lets you change are updated to match the code. `policy` and `partition` are fixed at creation.
+
+## Process jobs
+
+```ts
+@Processor('email')
+@Injectable()
+export class EmailProcessor {
+  constructor(private readonly mailer: MailService) {}
+
+  @Process()
+  async send(job: Job<SendEmail>) {
+    await this.mailer.deliver(job.data);   // throwing fails the job and triggers a retry
+  }
+
+  @ProcessBatch('email-digest', { batchSize: 50 })
+  async digest(jobs: Job<Digest>[]) {}
+
+  @Process('reports')
+  @Schedule('0 3 * * *', { tz: 'Europe/Paris', data: { kind: 'daily' } })
+  async nightly(job: Job<{ kind: string }>) {}
+}
+```
+
+Processors are normal providers, so they can inject anything. They must be singleton-scoped.
+
+## Enqueue inside your own transaction
+
+Every write method on `JobQueue` accepts pg-boss's `db` option. Wrap your ORM's transaction with the matching adapter and the job commits or rolls back with your data:
+
+```ts
+await this.knex.transaction(async (trx) => {
+  const [order] = await trx('orders').insert(dto).returning('*');
+  await this.queue.send({ orderId: order.id }, { db: fromKnex(trx) });   // or fromKysely / fromDrizzle / fromPrisma
+});
+```
+
+## Escape hatch
+
+`PgBossService.boss` is the raw `PgBoss` instance. `PgBossService.isHealthy()` is a database ping for readiness probes.
+
+## Behaviour worth knowing
+
+- pg-boss starts inside an async provider, so anything that injects a queue gets a ready database regardless of module init order.
+- The `error` and `warning` events are routed to the Nest `Logger`. An unhandled `error` event would otherwise crash the process.
+- A processor method that throws is logged with the queue name and job id, then rethrown so pg-boss applies the retry policy.
+- A queue named by `@Process` but not declared with `registerQueue` is created with pg-boss defaults.
+- Dead letter queues are created before the queues that point at them.

package/dist/decorators/inject-queue.decorator.d.ts

@@ -0,0 +1,2 @@
+/** Injects the `JobQueue` registered for `name` with `PgBossModule.registerQueue()`. */
+export declare const InjectQueue: (name: string) => ParameterDecorator & PropertyDecorator;

package/dist/decorators/inject-queue.decorator.js

@@ -0,0 +1,4 @@
+import { Inject } from '@nestjs/common';
+import { getQueueToken } from '../utils/get-queue-token.util.js';
+/** Injects the `JobQueue` registered for `name` with `PgBossModule.registerQueue()`. */
+export const InjectQueue = (name) => Inject(getQueueToken(name));

package/dist/decorators/processor.decorators.d.ts

@@ -0,0 +1,52 @@
+import type { ScheduleOptions, WorkOptions } from 'pg-boss';
+/**
+ * `perJobResults` changes the handler contract (it must return a result per job), so it is not
+ * exposed here. Use the `PgBossService` escape hatch if you need it.
+ */
+export type ProcessOptions = Omit<WorkOptions, 'batchSize' | 'perJobResults'>;
+export type ProcessBatchOptions = Omit<WorkOptions, 'perJobResults'>;
+export type ScheduleDecoratorOptions = ScheduleOptions & {
+    data?: object;
+};
+export interface ProcessorMetadata {
+    queue?: string;
+}
+export interface ProcessMetadata {
+    queue?: string;
+    options: WorkOptions;
+    batch: boolean;
+}
+export interface ScheduleMetadata {
+    cron: string;
+    options: ScheduleDecoratorOptions;
+}
+export declare const ProcessorMarker: import("@nestjs/core").DiscoverableDecorator<ProcessorMetadata>;
+export declare const ProcessMarker: import("@nestjs/core").DiscoverableDecorator<ProcessMetadata>;
+export declare const ScheduleMarker: import("@nestjs/core").DiscoverableDecorator<ScheduleMetadata>;
+/**
+ * Marks a provider as a job processor so its `@Process` / `@ProcessBatch` methods are registered
+ * as pg-boss workers. `queue` is the default for methods that don't name one.
+ *
+ * ```ts
+ * @Processor('email')
+ * export class EmailProcessor {
+ *   @Process()
+ *   async send(job: Job<SendEmailPayload>) {}
+ * }
+ * ```
+ */
+export declare const Processor: (queue?: string) => import("@nestjs/common").CustomDecorator;
+/**
+ * Handles one job at a time. The method receives the job (and, with `transactional: true`, the
+ * transaction as a second argument). Throwing fails the job and lets pg-boss retry it according
+ * to the queue's retry settings.
+ */
+export declare const Process: (queue?: string, options?: ProcessOptions) => import("@nestjs/common").CustomDecorator;
+/** Handles up to `batchSize` jobs per call. The method receives an array of jobs. */
+export declare const ProcessBatch: (queue?: string, options?: ProcessBatchOptions) => import("@nestjs/common").CustomDecorator;
+/**
+ * Runs the decorated `@Process` method on a cron expression or RFC 5545 recurrence rule.
+ * The schedule is stored in Postgres, so a fleet of instances produces one job per tick.
+ * Pass `data` to set the job payload.
+ */
+export declare const Schedule: (cron: string, options?: ScheduleDecoratorOptions) => import("@nestjs/common").CustomDecorator;

package/dist/decorators/processor.decorators.js

@@ -0,0 +1,31 @@
+import { DiscoveryService } from '@nestjs/core';
+export const ProcessorMarker = DiscoveryService.createDecorator();
+export const ProcessMarker = DiscoveryService.createDecorator();
+export const ScheduleMarker = DiscoveryService.createDecorator();
+/**
+ * Marks a provider as a job processor so its `@Process` / `@ProcessBatch` methods are registered
+ * as pg-boss workers. `queue` is the default for methods that don't name one.
+ *
+ * ```ts
+ * @Processor('email')
+ * export class EmailProcessor {
+ *   @Process()
+ *   async send(job: Job<SendEmailPayload>) {}
+ * }
+ * ```
+ */
+export const Processor = (queue) => ProcessorMarker({ queue });
+/**
+ * Handles one job at a time. The method receives the job (and, with `transactional: true`, the
+ * transaction as a second argument). Throwing fails the job and lets pg-boss retry it according
+ * to the queue's retry settings.
+ */
+export const Process = (queue, options = {}) => ProcessMarker({ queue, options: { ...options, batchSize: 1 }, batch: false });
+/** Handles up to `batchSize` jobs per call. The method receives an array of jobs. */
+export const ProcessBatch = (queue, options = {}) => ProcessMarker({ queue, options, batch: true });
+/**
+ * Runs the decorated `@Process` method on a cron expression or RFC 5545 recurrence rule.
+ * The schedule is stored in Postgres, so a fleet of instances produces one job per tick.
+ * Pass `data` to set the job payload.
+ */
+export const Schedule = (cron, options = {}) => ScheduleMarker({ cron, options });

package/dist/explorer/pg-boss.explorer.d.ts

@@ -0,0 +1,22 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import type { PgBoss } from 'pg-boss';
+import type { PgBossModuleOptions } from '../interfaces/pg-boss-module-options.interface.js';
+import { QueueRegistry } from '../queue/queue.registry.js';
+/**
+ * On bootstrap, finds every `@Processor()` provider and registers its `@Process` methods as
+ * pg-boss workers and its `@Schedule` methods as schedules. Runs after all providers exist, so
+ * a processor can depend on anything in the application.
+ */
+export declare class PgBossExplorer implements OnApplicationBootstrap {
+    private readonly boss;
+    private readonly options;
+    private readonly discovery;
+    private readonly scanner;
+    private readonly registry;
+    private readonly logger;
+    constructor(boss: PgBoss, options: PgBossModuleOptions, discovery: DiscoveryService, scanner: MetadataScanner, registry: QueueRegistry);
+    onApplicationBootstrap(): Promise<void>;
+    private registerProcessor;
+    private createHandler;
+}

package/dist/explorer/pg-boss.explorer.js

@@ -0,0 +1,104 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { MODULE_OPTIONS_TOKEN } from '../pg-boss.module-definition.js';
+import { PGBOSS_INSTANCE, PGBOSS_LOGGER_CONTEXT } from '../pg-boss.constants.js';
+import { QueueRegistry } from '../queue/queue.registry.js';
+import { ProcessMarker, ProcessorMarker, ScheduleMarker } from '../decorators/processor.decorators.js';
+/**
+ * On bootstrap, finds every `@Processor()` provider and registers its `@Process` methods as
+ * pg-boss workers and its `@Schedule` methods as schedules. Runs after all providers exist, so
+ * a processor can depend on anything in the application.
+ */
+let PgBossExplorer = class PgBossExplorer {
+    boss;
+    options;
+    discovery;
+    scanner;
+    registry;
+    logger = new Logger(PGBOSS_LOGGER_CONTEXT);
+    constructor(boss, options, discovery, scanner, registry) {
+        this.boss = boss;
+        this.options = options;
+        this.discovery = discovery;
+        this.scanner = scanner;
+        this.registry = registry;
+    }
+    async onApplicationBootstrap() {
+        if (this.options.registerWorkers === false) {
+            return;
+        }
+        const processors = this.discovery.getProviders({ metadataKey: ProcessorMarker.KEY });
+        for (const wrapper of processors) {
+            await this.registerProcessor(wrapper);
+        }
+    }
+    async registerProcessor(wrapper) {
+        const { instance } = wrapper;
+        const className = wrapper.metatype?.name ?? 'UnknownProcessor';
+        if (!instance) {
+            return;
+        }
+        if (!wrapper.isDependencyTreeStatic()) {
+            // A worker is a long-lived singleton, so a request- or transient-scoped class can't back one.
+            this.logger.warn(`${className} is not singleton-scoped, so its workers were not registered.`);
+            return;
+        }
+        const processor = this.discovery.getMetadataByDecorator(ProcessorMarker, wrapper);
+        const prototype = Object.getPrototypeOf(instance);
+        for (const methodName of this.scanner.getAllMethodNames(prototype)) {
+            const process = this.discovery.getMetadataByDecorator(ProcessMarker, wrapper, methodName);
+            const schedule = this.discovery.getMetadataByDecorator(ScheduleMarker, wrapper, methodName);
+            const where = `${className}.${methodName}`;
+            if (!process) {
+                if (schedule) {
+                    throw new Error(`${where} has @Schedule but no @Process, so there is nothing to run on the schedule.`);
+                }
+                continue;
+            }
+            const queue = process.queue ?? processor?.queue;
+            if (!queue) {
+                throw new Error(`${where} has no queue. Name it in @Process('queue') or in @Processor('queue').`);
+            }
+            await this.registry.ensure(queue);
+            const method = instance[methodName].bind(instance);
+            await this.boss.work(queue, process.options, this.createHandler(queue, method, process.batch));
+            this.logger.log(`${where} is processing "${queue}"`);
+            if (schedule) {
+                const { data, ...scheduleOptions } = schedule.options;
+                await this.boss.schedule(queue, schedule.cron, data ?? null, scheduleOptions);
+                this.logger.log(`${where} is scheduled on "${schedule.cron}"`);
+            }
+        }
+    }
+    createHandler(queue, method, batch) {
+        return async (jobs, tx) => {
+            try {
+                return await method(batch ? jobs : jobs[0], tx);
+            }
+            catch (error) {
+                const ids = jobs.map((job) => job.id).join(', ');
+                const reason = error instanceof Error ? error : new Error(String(error));
+                this.logger.error(`"${queue}" job ${ids} failed: ${reason.message}`, reason.stack);
+                throw error;
+            }
+        };
+    }
+};
+PgBossExplorer = __decorate([
+    Injectable(),
+    __param(0, Inject(PGBOSS_INSTANCE)),
+    __param(1, Inject(MODULE_OPTIONS_TOKEN)),
+    __param(2, Inject(DiscoveryService)),
+    __param(3, Inject(MetadataScanner)),
+    __param(4, Inject(QueueRegistry))
+], PgBossExplorer);
+export { PgBossExplorer };

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { PgBossModule } from './pg-boss.module.js';
+export { PgBossService } from './pg-boss.service.js';
+export { PGBOSS_INSTANCE } from './pg-boss.constants.js';
+export { JobQueue } from './queue/job-queue.js';
+export { QueueRegistry } from './queue/queue.registry.js';
+export { InjectQueue } from './decorators/inject-queue.decorator.js';
+export { Processor, Process, ProcessBatch, Schedule } from './decorators/processor.decorators.js';
+export type { ProcessOptions, ProcessBatchOptions, ScheduleDecoratorOptions, } from './decorators/processor.decorators.js';
+export { getQueueToken } from './utils/get-queue-token.util.js';
+export type { PgBossModuleOptions } from './interfaces/pg-boss-module-options.interface.js';
+export type { QueueDefinition } from './interfaces/queue-definition.interface.js';
+export { fromKnex, fromKysely, fromDrizzle, fromPrisma } from 'pg-boss';
+export type { Job, JobWithMetadata, SendOptions, Db } from 'pg-boss';

package/dist/index.js

@@ -0,0 +1,10 @@
+export { PgBossModule } from './pg-boss.module.js';
+export { PgBossService } from './pg-boss.service.js';
+export { PGBOSS_INSTANCE } from './pg-boss.constants.js';
+export { JobQueue } from './queue/job-queue.js';
+export { QueueRegistry } from './queue/queue.registry.js';
+export { InjectQueue } from './decorators/inject-queue.decorator.js';
+export { Processor, Process, ProcessBatch, Schedule } from './decorators/processor.decorators.js';
+export { getQueueToken } from './utils/get-queue-token.util.js';
+// Transaction adapters, so callers don't need a second import from 'pg-boss'.
+export { fromKnex, fromKysely, fromDrizzle, fromPrisma } from 'pg-boss';

package/dist/interfaces/pg-boss-module-options.interface.d.ts

@@ -0,0 +1,23 @@
+import type { ConstructorOptions, PgBoss, StopOptions } from 'pg-boss';
+type StartOptions = NonNullable<Parameters<PgBoss['start']>[0]>;
+/**
+ * Everything `new PgBoss(...)` accepts (connection, schema, maintenance, scheduling, ...),
+ * plus a few options that control how the module drives its lifecycle.
+ */
+export interface PgBossModuleOptions extends ConstructorOptions {
+    /** Passed to `boss.start()`, e.g. `{ attempts: 5 }` to ride out a database that is still booting. */
+    start?: StartOptions;
+    /**
+     * Passed to `boss.stop()` on application shutdown.
+     * @default { graceful: true, timeout: 30_000 }
+     */
+    stop?: StopOptions;
+    /**
+     * Register `@Process` workers and `@Schedule` schedules when the app boots.
+     * Set to `false` in processes that only enqueue jobs (an HTTP API, for example)
+     * so that a separate worker deployment does the processing.
+     * @default true
+     */
+    registerWorkers?: boolean;
+}
+export {};

package/dist/interfaces/pg-boss-module-options.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/queue-definition.interface.d.ts

@@ -0,0 +1,7 @@
+import type { Queue } from 'pg-boss';
+/**
+ * A queue declared in code. The module creates it on boot and, when it already exists,
+ * reconciles the options pg-boss allows changing so the code stays the source of truth.
+ * `policy` and `partition` are fixed at creation time.
+ */
+export type QueueDefinition = Queue;

package/dist/interfaces/queue-definition.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/pg-boss.constants.d.ts

@@ -0,0 +1,5 @@
+/** Injection token for the underlying, already-started `PgBoss` instance. */
+export declare const PGBOSS_INSTANCE: unique symbol;
+export declare const PGBOSS_LOGGER_CONTEXT = "PgBoss";
+/** Prefix used to build the injection token of a registered queue. */
+export declare const QUEUE_TOKEN_PREFIX = "PgBossQueue";

package/dist/pg-boss.constants.js

@@ -0,0 +1,5 @@
+/** Injection token for the underlying, already-started `PgBoss` instance. */
+export const PGBOSS_INSTANCE = Symbol('PGBOSS_INSTANCE');
+export const PGBOSS_LOGGER_CONTEXT = 'PgBoss';
+/** Prefix used to build the injection token of a registered queue. */
+export const QUEUE_TOKEN_PREFIX = 'PgBossQueue';

package/dist/pg-boss.module-definition.d.ts

@@ -0,0 +1,2 @@
+import type { PgBossModuleOptions } from './interfaces/pg-boss-module-options.interface.js';
+export declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<PgBossModuleOptions, "forRoot", "create", {}>, MODULE_OPTIONS_TOKEN: string | symbol, OPTIONS_TYPE: PgBossModuleOptions & Partial<{}>, ASYNC_OPTIONS_TYPE: import("@nestjs/common").ConfigurableModuleAsyncOptions<PgBossModuleOptions, "create"> & Partial<{}>;

package/dist/pg-boss.module-definition.js

@@ -0,0 +1,4 @@
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE, } = new ConfigurableModuleBuilder({ moduleName: 'PgBoss' })
+    .setClassMethodName('forRoot')
+    .build();

package/dist/pg-boss.module.d.ts

@@ -0,0 +1,14 @@
+import { type DynamicModule } from '@nestjs/common';
+import { ASYNC_OPTIONS_TYPE, ConfigurableModuleClass, OPTIONS_TYPE } from './pg-boss.module-definition.js';
+import type { QueueDefinition } from './interfaces/queue-definition.interface.js';
+export declare class PgBossModule extends ConfigurableModuleClass {
+    /** Configure pg-boss once, in the root module. */
+    static forRoot(options: typeof OPTIONS_TYPE): DynamicModule;
+    /** Same as `forRoot`, with `useFactory` / `useClass` / `useExisting`, e.g. to read `ConfigService`. */
+    static forRootAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
+    /**
+     * Declare queues in the module that owns them. Each is created (or reconciled) on boot and can be
+     * injected with `@InjectQueue(name)`. A bare string declares a queue with pg-boss defaults.
+     */
+    static registerQueue(...queues: (string | QueueDefinition)[]): DynamicModule;
+}

package/dist/pg-boss.module.js

@@ -0,0 +1,72 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var PgBossModule_1;
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { ASYNC_OPTIONS_TYPE, ConfigurableModuleClass, OPTIONS_TYPE } from './pg-boss.module-definition.js';
+import { PGBOSS_INSTANCE } from './pg-boss.constants.js';
+import { pgBossInstanceProvider } from './pg-boss.providers.js';
+import { PgBossService } from './pg-boss.service.js';
+import { PgBossExplorer } from './explorer/pg-boss.explorer.js';
+import { QueueRegistry } from './queue/queue.registry.js';
+import { JobQueue } from './queue/job-queue.js';
+import { getQueueToken } from './utils/get-queue-token.util.js';
+const coreProviders = [pgBossInstanceProvider, QueueRegistry, PgBossService, PgBossExplorer];
+/** The core is global (like `TypeOrmModule`), so feature modules only need `registerQueue`. */
+function asGlobalCore(definition) {
+    return {
+        ...definition,
+        global: true,
+        imports: [...(definition.imports ?? []), DiscoveryModule],
+        providers: [...(definition.providers ?? []), ...coreProviders],
+        exports: [PGBOSS_INSTANCE, PgBossService, QueueRegistry],
+    };
+}
+let PgBossModule = PgBossModule_1 = class PgBossModule extends ConfigurableModuleClass {
+    /** Configure pg-boss once, in the root module. */
+    static forRoot(options) {
+        return asGlobalCore(super.forRoot(options));
+    }
+    /** Same as `forRoot`, with `useFactory` / `useClass` / `useExisting`, e.g. to read `ConfigService`. */
+    static forRootAsync(options) {
+        return asGlobalCore(super.forRootAsync(options));
+    }
+    /**
+     * Declare queues in the module that owns them. Each is created (or reconciled) on boot and can be
+     * injected with `@InjectQueue(name)`. A bare string declares a queue with pg-boss defaults.
+     */
+    static registerQueue(...queues) {
+        const definitions = queues.map((queue) => (typeof queue === 'string' ? { name: queue } : queue));
+        // The definition is also a `useValue` provider so it is part of the module's metadata. Nest
+        // identifies a dynamic module by hashing that metadata (function bodies by their source text), so
+        // options held only in a closure would make two different declarations of one queue look identical.
+        const providers = definitions.flatMap((definition) => {
+            const definitionToken = `${getQueueToken(definition.name)}:definition`;
+            return [
+                { provide: definitionToken, useValue: definition },
+                {
+                    provide: getQueueToken(definition.name),
+                    inject: [definitionToken, QueueRegistry, PGBOSS_INSTANCE],
+                    useFactory: async (declared, registry, boss) => {
+                        registry.declare(declared);
+                        await registry.ensure(declared.name);
+                        return new JobQueue(declared.name, boss);
+                    },
+                },
+            ];
+        });
+        return {
+            module: PgBossModule_1,
+            providers,
+            exports: definitions.map((definition) => getQueueToken(definition.name)),
+        };
+    }
+};
+PgBossModule = PgBossModule_1 = __decorate([
+    Module({})
+], PgBossModule);
+export { PgBossModule };

package/dist/pg-boss.providers.d.ts

@@ -0,0 +1,8 @@
+import { type FactoryProvider } from '@nestjs/common';
+import { PgBoss } from 'pg-boss';
+/**
+ * Builds and starts pg-boss as an async provider. Because it only resolves once `start()` has
+ * finished, anything that injects the instance (queues, services) is guaranteed a ready database,
+ * whatever order Nest initializes modules in.
+ */
+export declare const pgBossInstanceProvider: FactoryProvider<PgBoss>;

package/dist/pg-boss.providers.js

@@ -0,0 +1,29 @@
+import { Logger } from '@nestjs/common';
+import { PgBoss } from 'pg-boss';
+import { MODULE_OPTIONS_TOKEN } from './pg-boss.module-definition.js';
+import { PGBOSS_INSTANCE, PGBOSS_LOGGER_CONTEXT } from './pg-boss.constants.js';
+/**
+ * Builds and starts pg-boss as an async provider. Because it only resolves once `start()` has
+ * finished, anything that injects the instance (queues, services) is guaranteed a ready database,
+ * whatever order Nest initializes modules in.
+ */
+export const pgBossInstanceProvider = {
+    provide: PGBOSS_INSTANCE,
+    inject: [MODULE_OPTIONS_TOKEN],
+    useFactory: async (options) => {
+        const { start, stop, registerWorkers, ...bossOptions } = options;
+        const logger = new Logger(PGBOSS_LOGGER_CONTEXT);
+        const boss = new PgBoss(bossOptions);
+        // pg-boss is an EventEmitter: an unhandled 'error' event would crash the process.
+        boss.on('error', (error) => logger.error(error.message, error.stack));
+        boss.on('warning', (warning) => logger.warn(warning.message));
+        try {
+            await boss.start(start);
+        }
+        catch (error) {
+            await boss.stop({ close: true, graceful: false }).catch(() => undefined);
+            throw error;
+        }
+        return boss;
+    },
+};

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

@@ -0,0 +1,16 @@
+import { type OnApplicationShutdown } from '@nestjs/common';
+import type { PgBoss } from 'pg-boss';
+import type { PgBossModuleOptions } from './interfaces/pg-boss-module-options.interface.js';
+/**
+ * Owns shutdown of the pg-boss instance and exposes it for anything the module doesn't wrap.
+ * Call `app.enableShutdownHooks()` so SIGTERM drains in-flight jobs before the process exits.
+ */
+export declare class PgBossService implements OnApplicationShutdown {
+    readonly boss: PgBoss;
+    private readonly options;
+    private readonly logger;
+    constructor(boss: PgBoss, options: PgBossModuleOptions);
+    onApplicationShutdown(): Promise<void>;
+    /** True when the database answers. Suited to a readiness probe. */
+    isHealthy(): Promise<boolean>;
+}

package/dist/pg-boss.service.js

@@ -0,0 +1,51 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { MODULE_OPTIONS_TOKEN } from './pg-boss.module-definition.js';
+import { PGBOSS_INSTANCE, PGBOSS_LOGGER_CONTEXT } from './pg-boss.constants.js';
+const DEFAULT_STOP = { graceful: true, timeout: 30_000 };
+/**
+ * Owns shutdown of the pg-boss instance and exposes it for anything the module doesn't wrap.
+ * Call `app.enableShutdownHooks()` so SIGTERM drains in-flight jobs before the process exits.
+ */
+let PgBossService = class PgBossService {
+    boss;
+    options;
+    logger = new Logger(PGBOSS_LOGGER_CONTEXT);
+    constructor(boss, options) {
+        this.boss = boss;
+        this.options = options;
+    }
+    async onApplicationShutdown() {
+        try {
+            await this.boss.stop({ ...DEFAULT_STOP, ...this.options.stop });
+        }
+        catch (error) {
+            // Shutdown must not throw: other modules still need their own hooks to run.
+            this.logger.error('Failed to stop pg-boss cleanly', error instanceof Error ? error.stack : String(error));
+        }
+    }
+    /** True when the database answers. Suited to a readiness probe. */
+    async isHealthy() {
+        try {
+            await this.boss.getDb().executeSql('SELECT 1');
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+};
+PgBossService = __decorate([
+    Injectable(),
+    __param(0, Inject(PGBOSS_INSTANCE)),
+    __param(1, Inject(MODULE_OPTIONS_TOKEN))
+], PgBossService);
+export { PgBossService };

package/dist/queue/job-queue.d.ts

@@ -0,0 +1,36 @@
+import type { CommandResponse, ConnectionOptions, JobInsert, JobWithMetadata, PgBoss, QueueResult, Schedule, ScheduleOptions, SendOptions } from 'pg-boss';
+/**
+ * A handle on one queue, typed by the payload it carries. Obtain it with `@InjectQueue('name')`.
+ *
+ * Every method that writes accepts pg-boss's `db` option, so a job can be enqueued in the same
+ * transaction as your own writes (see `fromKnex`, `fromKysely`, `fromDrizzle`, `fromPrisma`).
+ */
+export declare class JobQueue<TData extends object = object> {
+    readonly name: string;
+    private readonly boss;
+    constructor(name: string, boss: PgBoss);
+    send(data: TData, options?: SendOptions): Promise<string | null>;
+    /** Delay the job: a `Date`, an ISO string, or a number of seconds from now. */
+    sendAfter(data: TData, after: Date | string | number, options?: SendOptions | null): Promise<string | null>;
+    /** At most one job per `seconds` window (per `key`), the first one wins. */
+    sendThrottled(data: TData, seconds: number, key?: string, options?: SendOptions | null): Promise<string | null>;
+    /** At most one job per `seconds` window (per `key`), the last one wins. */
+    sendDebounced(data: TData, seconds: number, key?: string, options?: SendOptions | null): Promise<string | null>;
+    /** Bulk insert. Cheaper than calling `send` in a loop. */
+    insert(jobs: JobInsert<TData>[], options?: ConnectionOptions): Promise<string[] | null>;
+    /** Create or update a recurring job. Idempotent per `(queue, key)`, so calling it on every boot is safe. */
+    schedule(cron: string, data?: TData | null, options?: ScheduleOptions): Promise<void>;
+    unschedule(key?: string, options?: ConnectionOptions): Promise<void>;
+    getSchedules(key?: string): Promise<Schedule[]>;
+    findJobs(options?: Parameters<PgBoss['findJobs']>[1]): Promise<JobWithMetadata<TData>[]>;
+    cancel(id: string | string[], options?: ConnectionOptions): Promise<CommandResponse>;
+    retry(id: string | string[], options?: ConnectionOptions): Promise<CommandResponse>;
+    deleteJob(id: string | string[], options?: ConnectionOptions): Promise<CommandResponse>;
+    /**
+     * Call on a dead letter queue's handle: moves its jobs back to the queues they failed in.
+     * Filter with `sourceName`, `ids`, `data` or `createdBefore`. Returns how many moved.
+     */
+    redrive(options?: Parameters<PgBoss['redrive']>[1]): Promise<number>;
+    /** Queue definition plus live counts (queued, active, deferred, ...). */
+    getInfo(): Promise<QueueResult | null>;
+}

package/dist/queue/job-queue.js

@@ -0,0 +1,67 @@
+/**
+ * A handle on one queue, typed by the payload it carries. Obtain it with `@InjectQueue('name')`.
+ *
+ * Every method that writes accepts pg-boss's `db` option, so a job can be enqueued in the same
+ * transaction as your own writes (see `fromKnex`, `fromKysely`, `fromDrizzle`, `fromPrisma`).
+ */
+export class JobQueue {
+    name;
+    boss;
+    constructor(name, boss) {
+        this.name = name;
+        this.boss = boss;
+    }
+    send(data, options) {
+        return this.boss.send(this.name, data, options);
+    }
+    /** Delay the job: a `Date`, an ISO string, or a number of seconds from now. */
+    sendAfter(data, after, options = null) {
+        // pg-boss overloads sendAfter per argument type, which a union can't select; the runtime accepts all three.
+        return this.boss.sendAfter(this.name, data, options, after);
+    }
+    /** At most one job per `seconds` window (per `key`), the first one wins. */
+    sendThrottled(data, seconds, key, options = null) {
+        return this.boss.sendThrottled(this.name, data, options, seconds, key);
+    }
+    /** At most one job per `seconds` window (per `key`), the last one wins. */
+    sendDebounced(data, seconds, key, options = null) {
+        return this.boss.sendDebounced(this.name, data, options, seconds, key);
+    }
+    /** Bulk insert. Cheaper than calling `send` in a loop. */
+    insert(jobs, options) {
+        return this.boss.insert(this.name, jobs, options);
+    }
+    /** Create or update a recurring job. Idempotent per `(queue, key)`, so calling it on every boot is safe. */
+    schedule(cron, data, options) {
+        return this.boss.schedule(this.name, cron, data, options);
+    }
+    unschedule(key, options) {
+        return this.boss.unschedule(this.name, key, options);
+    }
+    getSchedules(key) {
+        return this.boss.getSchedules(this.name, key);
+    }
+    findJobs(options) {
+        return this.boss.findJobs(this.name, options);
+    }
+    cancel(id, options) {
+        return this.boss.cancel(this.name, id, options);
+    }
+    retry(id, options) {
+        return this.boss.retry(this.name, id, options);
+    }
+    deleteJob(id, options) {
+        return this.boss.deleteJob(this.name, id, options);
+    }
+    /**
+     * Call on a dead letter queue's handle: moves its jobs back to the queues they failed in.
+     * Filter with `sourceName`, `ids`, `data` or `createdBefore`. Returns how many moved.
+     */
+    redrive(options) {
+        return this.boss.redrive(this.name, options);
+    }
+    /** Queue definition plus live counts (queued, active, deferred, ...). */
+    getInfo() {
+        return this.boss.getQueue(this.name);
+    }
+}

package/dist/queue/queue.registry.d.ts

@@ -0,0 +1,16 @@
+import type { PgBoss } from 'pg-boss';
+import type { QueueDefinition } from '../interfaces/queue-definition.interface.js';
+/**
+ * Knows every queue declared through `PgBossModule.registerQueue()` and makes sure each one
+ * exists in the database exactly once per process before anything uses it.
+ */
+export declare class QueueRegistry {
+    private readonly boss;
+    private readonly definitions;
+    private readonly ready;
+    constructor(boss: PgBoss);
+    declare(definition: QueueDefinition): void;
+    /** Resolves once the queue, and its dead letter queue if any, exist and match the declaration. */
+    ensure(name: string): Promise<void>;
+    private create;
+}

package/dist/queue/queue.registry.js

@@ -0,0 +1,69 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from '@nestjs/common';
+import { PGBOSS_INSTANCE } from '../pg-boss.constants.js';
+/**
+ * Knows every queue declared through `PgBossModule.registerQueue()` and makes sure each one
+ * exists in the database exactly once per process before anything uses it.
+ */
+let QueueRegistry = class QueueRegistry {
+    boss;
+    definitions = new Map();
+    ready = new Map();
+    constructor(boss) {
+        this.boss = boss;
+    }
+    declare(definition) {
+        const existing = this.definitions.get(definition.name);
+        if (existing && !isSameDefinition(existing, definition)) {
+            throw new Error(`Queue "${definition.name}" is registered twice with different options. ` +
+                'Register it once, or register it with identical options everywhere.');
+        }
+        this.definitions.set(definition.name, definition);
+        // A queue may have been created with defaults earlier (as another queue's dead letter queue)
+        // before its own declaration showed up. Forget that so the next ensure() reconciles it.
+        this.ready.delete(definition.name);
+    }
+    /** Resolves once the queue, and its dead letter queue if any, exist and match the declaration. */
+    ensure(name) {
+        let pending = this.ready.get(name);
+        if (!pending) {
+            pending = this.create(name).catch((error) => {
+                this.ready.delete(name);
+                throw error;
+            });
+            this.ready.set(name, pending);
+        }
+        return pending;
+    }
+    async create(name) {
+        const { name: _name, ...options } = this.definitions.get(name) ?? { name };
+        // pg-boss refuses to create a queue whose dead letter queue does not exist yet.
+        if (options.deadLetter) {
+            await this.ensure(options.deadLetter);
+        }
+        if (!(await this.boss.getQueue(name))) {
+            await this.boss.createQueue(name, options);
+            return;
+        }
+        const { policy, partition, retryDelayMax, heartbeatSeconds, ...updatable } = options;
+        if (Object.keys(updatable).length > 0) {
+            await this.boss.updateQueue(name, updatable);
+        }
+    }
+};
+QueueRegistry = __decorate([
+    Injectable(),
+    __param(0, Inject(PGBOSS_INSTANCE))
+], QueueRegistry);
+export { QueueRegistry };
+function isSameDefinition(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/utils/get-queue-token.util.d.ts

@@ -0,0 +1,2 @@
+/** Injection token of the `JobQueue` registered for `name`. */
+export declare function getQueueToken(name: string): string;

package/dist/utils/get-queue-token.util.js

@@ -0,0 +1,5 @@
+import { QUEUE_TOKEN_PREFIX } from '../pg-boss.constants.js';
+/** Injection token of the `JobQueue` registered for `name`. */
+export function getQueueToken(name) {
+    return `${QUEUE_TOKEN_PREFIX}:${name}`;
+}

package/package.json

@@ -1,6 +1,65 @@
-{
-  "name": "nestjs-pg-boss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "nestjs-pg-boss",
+  "version": "0.1.0",
+  "description": "NestJS module for pg-boss: declarative queues, decorator-based workers and schedules, and transactional enqueueing.",
+  "keywords": [
+    "nestjs",
+    "pg-boss",
+    "postgres",
+    "queue",
+    "jobs",
+    "background-jobs"
+  ],
+  "license": "MIT",
+  "author": "AbderraHman El Haddad Asofi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/4reha/nestjs-pg-boss.git"
+  },
+  "homepage": "https://github.com/4reha/nestjs-pg-boss#readme",
+  "bugs": {
+    "url": "https://github.com/4reha/nestjs-pg-boss/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm test && npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0 || ^12.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0 || ^12.0.0",
+    "pg-boss": "^12.0.0",
+    "reflect-metadata": "^0.1.12 || ^0.2.0",
+    "rxjs": "^7.1.0"
+  },
+  "devDependencies": {
+    "@electric-sql/pglite": "^0.5.12",
+    "@nestjs/common": "^12.3.2",
+    "@nestjs/core": "^12.3.2",
+    "@nestjs/testing": "^12.3.2",
+    "@types/node": "^26.6.5",
+    "pg-boss": "^12.38.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.2",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.5"
+  }
+}