Jobs

@halostack/jobs is a job queue built on pg-boss, which stores its queue in Postgres. It runs in-process alongside the API and reuses the existing @halostack/db Postgres instance, so there's no separate message broker to operate.

Importing

Everything comes from a single entrypoint, @halostack/jobs (src/index.ts):

• defineJob(descriptor) — declares a job, including its name, handler, retry policy, and schedule.
• jobs and createJobRunner() — the runner itself. Control its lifecycle with jobs.start() and jobs.stop().
• The supporting types: JobContext, JobDefinition, JobRetry, JobSchedule, and SendJobOptions.

Structure

The package is organized around defining jobs and running them:

• src/define-job.ts — the defineJob descriptor factory.
• src/registry.ts — collects every defined job.
• src/job-runner.ts — wires the registry into pg-boss and exposes jobs.
• src/interval.ts — cron and interval scheduling helpers.
• src/jobs/ — the actual job definitions, such as cleanup-expired-sessions.ts.

Conventions

To add a job, create a file under src/jobs/ that calls defineJob(...) and register it.

The runner is started by apps/api only when env.JOBS_ENABLED is set, and it's drained on SIGINT and SIGTERM. Because pg-boss redelivers a job that was interrupted mid-run, handlers must be idempotent — running the same job twice should be safe.

Migrate pg-boss's schema before the first run, and read all configuration through @halostack/env.