pg-boss-registry

library0.3.0jsnpmunverified

A typed queue registry and lifecycle helper library for pg-boss (^12.15.0), enabling TypeScript types for queue names, payloads, workers, and schedules. Current stable version 0.3.0, released under MIT license. Provides definePgBossQueues, asTypedPgBoss, and setupPgBoss to create typed PgBoss instances and workers with full type safety. Key differentiators: full TypeScript support, framework-agnostic (works with Fastify, Hono, Express, NestJS), typed worker error handling, and lifecycle management (start/stop/graceful shutdown).

database devops

npm install pg-boss-registry

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · PG-BOSS-REGISTRY

pg-boss-registry

databasejavascriptv0.3.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

definePgBossQueues

✓ import { definePgBossQueues } from 'pg-boss-registry'

✗ import { definePgBossQueues } from 'pg-boss'

ESM-only, pg-boss-registry is a separate package.

queue

✓ import { queue } from 'pg-boss-registry'

✗ const queue = require('pg-boss-registry').queue

ESM-only, named export.

setupPgBoss

✓ import { setupPgBoss } from 'pg-boss-registry'

✗ import { setupPgBoss } from 'pg-boss'

setupPgBoss is pg-boss-registry's own lifecycle manager, not from pg-boss.

asTypedPgBoss

✓ import { asTypedPgBoss } from 'pg-boss-registry'

✗ import { asTypedPgBoss } from './typed-boss'

Exported from pg-boss-registry, not a local file.

PgBossQueuesFromRegistry

✓ import { type PgBossQueuesFromRegistry } from 'pg-boss-registry'

Type-only import, only available in TypeScript.

Defines typed queues, creates workers with schedules, sets up PgBoss with full type safety, and demonstrates typed send.

import { PgBoss } from 'pg-boss' import { asTypedPgBoss, definePgBossQueues, queue, setupPgBoss, type PgBossQueuesFromRegistry, } from 'pg-boss-registry' type EmailJob = { userId: string } const queues = definePgBossQueues({ 'email/send': queue<EmailJob>({ create: true }), }) type Queues = PgBossQueuesFromRegistry<typeof queues> const boss = new PgBoss(process.env.POSTGRES_URL ?? '') const workers = [ queues.worker('email/send', { name: 'email-worker', schedule: { cron: '0 8 * * *', data: { userId: 'daily' } }, async handler(jobs) { for (const job of jobs) { job.data.userId } }, }), ] const setup = await setupPgBoss(boss, { start: true, queueRegistry: queues, workers, }) await setup.boss.send('email/send', { userId: 'user_123' }) const typedBoss = asTypedPgBoss<Queues>(boss) await typedBoss.send('email/send', { userId: 'user_456' })

Debug

Known issues

gotchaqueue<T>() payload type is not enforced at runtime; it only provides TypeScript compile-time safety.

fix

Use runtime validation (e.g., zod) within worker handlers if payload trust is low.

affects: >=0.0.0

gotchasetupPgBoss will not call boss.start() unless the start option is true; default is false.

fix

Explicitly pass start: true to setupPgBoss if you need automatic start.

affects: >=0.0.0

breakingRequires pg-boss ^12.15.0 as a peer dependency; older versions may cause type or runtime errors.

fix

Update pg-boss to version >=12.15.0 in your project.

affects: >=0.3.0

gotchaasTypedPgBoss<Queues>(boss) returns the same boss instance, not a wrapper; any mutations affect the original.

fix

Do not reassign the returned reference expecting a separate instance.

affects: >=0.0.0

deprecatedNo known deprecations yet in version 0.3.0.

fix

N/A

affects: >=0.3.0

Errors

Common errors & fixes

Cannot find module 'pg-boss-registry'

Package not installed or missing from node_modules.

fix

Run npm install pg-boss-registry

TypeError: boss.send is not a function

boss is not a PgBoss instance.

fix

Ensure you pass a valid PgBoss instance: const boss = new PgBoss(process.env.POSTGRES_URL)

Property 'worker' does not exist on type '...'.

Missing queue definition or incorrect usage of definePgBossQueues.

fix

Verify that queues object includes the queue key (e.g., 'email/send') and that worker is called on the correct queues object.

The 'schedule' option requires a 'cron' property of type string.

Incorrect schedule format or data type.

fix

Ensure schedule object contains cron: string and an optional data object matching the queue payload.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/inyourtime/pg-boss-registry ↗

packagepg-boss-registry ↗

homepagehttps://github.com/inyourtime/pg-boss-registry#readme ↗