bosskit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenny Williams
+
+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

@@ -0,0 +1,475 @@
+# bosskit
+
+Type-safe, user-scoped job queues for [pg-boss](https://github.com/timgit/pg-boss), powered by Zod.
+
+Declare each queue once with a Zod schema. Get a typed `enqueue`, typed worker
+handlers, runtime validation at both boundaries, and a compile error if you
+forget who a job is for.
+
+```ts
+import { createBoss, createJobPlatform, defineQueues, UserScopedSchema } from "bosskit";
+import { fromDrizzle } from "pg-boss";
+import { sql } from "drizzle-orm";
+import { z } from "zod";
+
+const QUEUES = defineQueues([
+  { name: "send-email-dlq", schema: UserScopedSchema.extend({ to: z.string() }) },
+  {
+    name: "send-email",
+    schema: UserScopedSchema.extend({ to: z.string() }),
+    options: { deadLetter: "send-email-dlq", notify: true, retryLimit: 3 },
+  },
+  // `global: true` opts a queue out of the user-scoped default — see below.
+  {
+    name: "nightly-cleanup",
+    global: true,
+    schema: z.object({ olderThanDays: z.number() }),
+  },
+]);
+
+export const { enqueue, defineWorker, ensureQueues, applySchedules } = createJobPlatform({
+  definitions: QUEUES,
+  getBoss: async () => boss,
+  getRuntime: async () => ({ db, mailer }),
+  toBossDb: (handle: Db) => fromDrizzle(handle, sql),
+  logger: console,
+});
+
+// Fully typed — the payload shape comes from the queue's schema:
+await enqueue({ db, queue: "send-email", data: { to: "a@b.com", userId: "user_123" } });
+
+// @ts-expect-error send-email-dlq is a dead-letter target, not enqueue-able
+await enqueue({ db, queue: "send-email-dlq", data: { to: "a@b.com", userId: "user_123" } });
+```
+
+Call `ensureQueues(boss)` once on boot, before enqueuing to or working any
+queue — it creates whatever queue in the registry pg-boss doesn't have yet,
+and syncs options on the ones it does. See
+[`createJobPlatform`](#createjobplatformoptions) below for what each of the
+seven returned functions does.
+
+## Install
+
+```sh
+pnpm add bosskit pg-boss zod
+```
+
+Requires Node `>=22.12`. This package is ESM-only — there is no CommonJS
+build, so `require("bosskit")` will not work.
+
+## Why
+
+Most pg-boss setups end up with a hand-written type per queue, a hand-written
+map from queue name to type, and a `boss.send`/`boss.work` call site that
+trusts both. The map and the calls drift from the schema over time, silently.
+
+bosskit collapses all of that into one Zod schema per queue:
+
+- The payload **type** for `enqueue` and for worker handlers is inferred from
+  the schema — no hand-written map to keep in sync.
+- The payload is **validated at runtime** against the same schema, both when
+  you enqueue and again when a worker picks the job up.
+- A queue named as another queue's `deadLetter` is automatically excluded from
+  the enqueue-able set — you cannot accidentally enqueue directly to a DLQ.
+- Every payload schema is required to carry the acting user, so a queue with
+  no notion of who it's for is a compile error, not a discovery made while
+  reading a dead-letter row.
+- Zero runtime dependencies. `pg-boss` and `zod` are peer dependencies you
+  already have.
+
+## User-scoped by default
+
+Every queue is **user-scoped** unless it opts out. A user-scoped queue's
+schema must produce `userId: string` — the easiest way is to extend the
+`UserScopedSchema` base schema bosskit exports:
+
+```ts
+import { UserScopedSchema } from "bosskit";
+import { z } from "zod";
+
+const schema = UserScopedSchema.extend({ to: z.string() });
+// z.infer<typeof schema> is { userId: string; to: string }
+```
+
+System work that genuinely has no acting user — cron sweeps, maintenance jobs
+— opts out explicitly with `global: true` on the queue definition:
+
+```ts
+defineQueues([
+  {
+    name: "nightly-cleanup",
+    global: true,
+    schema: z.object({ olderThanDays: z.number() }),
+  },
+]);
+```
+
+`userId` lives in the job **payload**, not in pg-boss job metadata: put the
+acting user in the schema and it travels with the job automatically — it's
+still there on the row if the job ends up in a dead-letter queue, with no
+separate plumbing needed to know who a failed job was running for.
+
+## `defineQueues`
+
+Declare a registry by calling `defineQueues`, not by writing a plain type
+annotation:
+
+```ts
+const QUEUES = defineQueues([
+  { name: "send-email", schema: UserScopedSchema.extend({ to: z.string() }) },
+]);
+```
+
+This is what keeps `enqueue` and worker handlers precisely typed per queue —
+and it means there's no `as const satisfies QueueDefinition[]` incantation to
+remember at the call site.
+
+### The widening trap
+
+Three spellings keep the registry's types precise: `defineQueues([...])`, an
+array literal passed straight into `createJobPlatform`, and
+`[...] satisfies QueueDefinition[]`.
+
+Two spellings destroy them, and both type-check:
+
+```ts
+// Both compile. Both throw the registry's precise types away.
+const widened: QueueDefinition[] = [
+  { name: "send-email", schema: UserScopedSchema.extend({ to: z.string() }) },
+];
+const alsoWidened: readonly QueueDefinition[] = [
+  { name: "send-email", schema: UserScopedSchema.extend({ to: z.string() }) },
+];
+```
+
+`readonly` does not save you. The symptom: `enqueue` stops catching wrong
+payloads — every queue's payload collapses to the base `{ userId: string }`
+shape — and stops rejecting dead-letter queue names, so
+`enqueue({ queue: "a-queue-that-does-not-exist", ... })` compiles too.
+
+If `enqueue` has stopped complaining about a payload you know is wrong, this
+is why.
+
+## Dead-letter queues
+
+Point a queue's `deadLetter` option at another queue's name:
+
+```ts
+defineQueues([
+  { name: "send-email-dlq", schema: UserScopedSchema.extend({ to: z.string() }) },
+  {
+    name: "send-email",
+    schema: UserScopedSchema.extend({ to: z.string() }),
+    options: { deadLetter: "send-email-dlq" },
+  },
+]);
+```
+
+Any queue named by some other queue's `deadLetter` is removed from the set
+`enqueue` accepts — this is derived from the registry, not a separate list you
+maintain, so a new DLQ is automatically protected the moment you declare it.
+pg-boss populates a DLQ itself when a job exhausts its retries; application
+code never sends to one directly.
+
+## Workers
+
+```ts
+const worker = defineWorker({
+  queue: "send-email",
+  options: { pollingIntervalSeconds: 2 },
+  handler: async ({ jobs, db, mailer }) => {
+    for (const job of jobs) {
+      await mailer.send({ to: job.data.to, userId: job.data.userId });
+    }
+  },
+});
+
+await worker.register(boss);
+```
+
+The handler's first argument is the runtime object returned by `getRuntime`
+(`{ db, mailer }` in the opening example) merged with `jobs` — an array of
+`JobWithMetadata<Payload>` whose `data` has already been run through the
+queue's schema, so schema coercions and defaults are applied before the
+handler sees them (a `z.coerce.date()` field arrives as a `Date`, not the
+string jsonb gave back). A handler never opens its own connection or parses a
+payload.
+
+Keep payload schemas JSON-round-trippable, and avoid `.transform()` on them —
+a job's payload is written as JSON and read back as JSON, so a schema whose
+parsed shape can't survive that round trip will fail validation on the way
+back out.
+
+Validation happens per **batch**, not per job: a payload that fails to parse
+fails the whole batch, so the healthy jobs fetched alongside it retry and can
+dead-letter along with it. This doesn't come up at the default `batchSize` of
+1; with a larger `batchSize`, one bad payload can drag its batch-mates down
+with it.
+
+Every job is logged before the handler runs, with its queue, job id, retry
+count, and the acting `userId` (when the queue is user-scoped) — so no
+handler has to remember to trace who a job is for.
+
+## Schedules
+
+```ts
+import type { QueueNameOf, ScheduleDefinition } from "bosskit";
+
+// QUEUES is the registry from the opening example, which declares nightly-cleanup.
+const schedules: ScheduleDefinition<QueueNameOf<typeof QUEUES>>[] = [
+  { queue: "nightly-cleanup", cron: "0 3 * * *", data: { olderThanDays: 30 }, options: { tz: "UTC" } },
+];
+
+await applySchedules(boss, schedules);
+```
+
+`QueueNameOf<typeof QUEUES>` is the registry's set of queue names, so a typo
+in `queue` is a compile error rather than a schedule that silently targets
+nothing.
+
+`applySchedules` (returned by `createJobPlatform`, alongside `enqueue` and
+`defineWorker`) is an idempotent sync: it upserts every schedule you pass in,
+then unschedules any schedule pg-boss still has recorded that you no longer
+declare. Call it on every boot with your full, current list of schedules —
+removing an entry from the list is how you turn a schedule off.
+
+## Adapters
+
+`enqueue` takes a `db` handle and adapts it to pg-boss's own database contract
+via the `toBossDb` function you pass to `createJobPlatform`. bosskit ships no
+adapter of its own and has no ORM dependency — pg-boss already exports one per
+client: `fromDrizzle`, `fromKnex`, `fromKysely`, `fromPrisma` and `fromPglite`.
+
+```ts
+import { fromDrizzle } from "pg-boss";
+import { sql } from "drizzle-orm";
+
+toBossDb: (handle: Db) => fromDrizzle(handle, sql);
+```
+
+Annotate `toBossDb`'s parameter — that type becomes `enqueue`'s `db` type.
+Left unannotated (`toBossDb: (handle) => ...`), `enqueue` will accept any
+value as `db` without complaint.
+
+One version note if you use drizzle over
+[postgres-js](https://github.com/porsager/postgres): pg-boss's `fromDrizzle`
+only handles postgres-js's bare row-array result from **12.26.3** onward — on
+12.21.0 through 12.26.2 it both rejects the handle at compile time and
+mis-reads the rows at runtime. Other drivers (node-postgres and friends,
+which return `{ rows }`) are fine across the whole supported range.
+
+Pass a transaction handle (not a pooled client) to make job creation atomic
+with your domain writes — see [Transactions](#transactions) below.
+
+### Writing your own
+
+pg-boss's `Db` contract is small: an object with one method,
+`executeSql(text, values?)`, returning `{ rows: unknown[] }`. Any client can
+satisfy it directly:
+
+```ts
+import type { Db } from "pg-boss";
+
+function fromMyClient(client: { query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }> }): Db {
+  return {
+    executeSql: (text, values) => client.query(text, values),
+  };
+}
+```
+
+Pass the result as `toBossDb` in `createJobPlatform`. Give the parameter an
+explicit type, as above — that type becomes `enqueue`'s `db` type.
+
+## Transactions
+
+`enqueue`'s `db` argument is whatever `toBossDb` accepts — typically a pool
+handle, but it can just as well be a transaction handle. Passing a
+transaction makes job creation atomic with the rest of that transaction's
+writes: if the transaction rolls back, the job was never created. pg-boss's
+NOTIFY (when `notify: true` is set on the queue) fires once the transaction
+commits, so a worker never picks up a job whose surrounding write hasn't
+landed yet.
+
+```ts
+await db.transaction(async (tx) => {
+  await tx.insert(emails).values({ to, userId });
+  await enqueue({ db: tx, queue: "send-email", data: { to, userId } });
+});
+```
+
+For `tx` to typecheck as `enqueue`'s `db` argument, the type you use for `Db`
+(the parameter type of your `toBossDb` function) must be drizzle's abstract
+`PgDatabase` supertype, not the type `drizzle(...)` itself returns — the
+concrete type rejects a transaction handle. With drizzle over postgres-js, the
+spelling that accepts both a pool handle and a transaction handle is:
+
+```ts
+import type { PgDatabase } from "drizzle-orm/pg-core";
+import type { PostgresJsQueryResultHKT } from "drizzle-orm/postgres-js";
+
+type Db = PgDatabase<PostgresJsQueryResultHKT, Record<string, unknown>>;
+```
+
+Both type arguments matter: leaving the schema parameter at its default
+(`Record<string, never>`) rejects a handle created with a schema, and the
+first one names the driver. Swap `PostgresJsQueryResultHKT` for your driver's
+equivalent (`NodePgQueryResultHKT`, and so on).
+
+## Testing / contributing
+
+Unit tests need no external services:
+
+```sh
+pnpm test
+```
+
+Integration tests exercise real pg-boss + Postgres round trips (queue
+creation, enqueue, worker delivery, schema validation) and need a Postgres
+reachable at `TEST_DATABASE_URL` that the test run may freely `CREATE` and
+`DROP` databases on. Point it at a disposable container, not anything you
+care about:
+
+```sh
+docker run --rm -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:18
+TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres pnpm test:integration
+```
+
+Each integration test file creates its own throwaway database (named after
+the test file) and drops it on teardown, so runs don't collide and leave
+nothing behind on success.
+
+Before sending a change:
+
+```sh
+pnpm check      # biome lint + format
+pnpm typecheck
+pnpm test
+pnpm test:integration
+pnpm build
+```
+
+`pnpm prepublishOnly` runs `check`, `typecheck`, `test`, and `build` before
+every release; `test:integration` is deliberately not part of it, so cutting a
+release doesn't require a disposable Postgres container on hand.
+
+## API reference
+
+### `createJobPlatform(options)`
+
+The framework's entry point. Takes `definitions` (a registry from
+`defineQueues`), `getBoss` (resolves a started `PgBoss` instance),
+`getRuntime` (resolves the context object passed to every worker handler),
+`toBossDb` (adapts your database handle to pg-boss's `Db` contract), and
+`logger`.
+
+Two rules to follow when writing the providers:
+
+- **Annotate `toBossDb`'s parameter.** That type becomes `enqueue`'s `db`
+  type. Written unannotated (`toBossDb: (db) => fromDrizzle(db, sql)`),
+  `enqueue` will accept literally any value as `db`, silently.
+- **`getRuntime` runs once.** Don't compute per-call values in it (a fresh
+  request id, `Date.now()`) — whatever it returns is what every handler gets
+  for the life of the platform. Return plain data, not a class instance.
+
+Returns `{ enqueue, enqueueWith, cancelJobs, defineWorker, ensureQueues,
+applySchedules, schemaFor }` bound to that registry:
+
+- **`enqueue`** — the sanctioned way to create a job. See the opening example.
+  Returns the new job's id, or `null` when pg-boss declined to create one
+  because the send was de-duplicated (a `singletonKey` already has a job in
+  flight, for instance). `null` is a normal outcome, not an error — check for
+  it before treating the return value as an id.
+- **`enqueueWith(boss, args)`** — the same as `enqueue`, but takes an explicit
+  `PgBoss` instance instead of resolving one through `getBoss`. Use it when
+  you already have a boss instance in hand — most usefully in tests, where it
+  avoids wiring a `getBoss` provider around the instance you already control.
+- **`cancelJobs(queue, jobIds)`** — best-effort cancellation by id (e.g. when
+  the domain record a job represents gets cancelled). Already-settled ids are
+  a no-op. Cancelling stops a queued job from starting and prevents a retry of
+  an active one, but does **not** abort a job already running on a worker —
+  interrupt that in-process.
+- **`defineWorker`** — see [Workers](#workers). `options` is optional —
+  omit it entirely for a worker with nothing to configure.
+- **`ensureQueues(boss)`** — creates any queue in the registry pg-boss doesn't
+  have yet, and updates options on ones that already exist (`policy` and
+  `partition` are immutable in pg-boss, so those are left alone on existing
+  queues). Note: pg-boss's `update_queue` COALESCEs unspecified options to
+  their current values, so removing an option from a definition does not
+  reset it on an already-created queue — that needs a fresh queue or manual
+  intervention. Call it on boot, before enqueuing to or working any queue.
+- **`applySchedules`** — see [Schedules](#schedules).
+- **`schemaFor(queue)`** — returns the queue's payload schema, typed so
+  `.parse()` returns that queue's payload. Use it to validate or parse a
+  payload yourself outside of `enqueue` or a worker handler. Throws
+  `JobPlatformError` for a name that is not in the registry.
+
+### `defineQueues(definitions)`
+
+Declares a queue registry. See [`defineQueues`](#definequeues) above. Returns
+the array unchanged — its only job is to pin the `const` type parameter. Each
+entry is a `QueueDefinition`: `name`, `schema`, an optional `global`, and an
+optional `options` (pg-boss's `createQueue` options minus `name`) — omit
+`options` entirely for a queue with nothing to configure.
+
+### `UserScopedSchema`
+
+`z.object({ userId: z.string() })`. The base schema every user-scoped queue's
+payload schema should `.extend()`.
+
+### `createBoss(options)`
+
+A thin, opinionated `PgBoss` factory: sets `application_name`, a default
+`max` pool size (`5`) and `schema` (`"pgboss"`), and wires the
+`error`/`warning` events to your logger so an unhandled pg-boss `error` event
+can't crash the process. Takes `connectionString`, `migrate`, and `logger`,
+with optional `max`, `applicationName` (defaults to `"bosskit"`), and
+`schema` (defaults to `"pgboss"`). Returns a plain `PgBoss` instance —
+starting, stopping, and caching it is still your responsibility.
+
+### `ScheduleDefinition<Name>` / `schedulesToRemove(declared, existing)`
+
+`ScheduleDefinition` is the shape passed to `applySchedules`: `{ queue, cron,
+data?, options? }`. `schedulesToRemove(declared, existing)` takes your
+declared schedule list and pg-boss's existing schedules (from
+`boss.getSchedules()`) and returns the ones that are no longer declared and
+would be turned off — useful for previewing what a call to `applySchedules`
+would unschedule before you actually run it. Application code normally only
+calls `applySchedules`, which does this diff for you.
+
+### `JobPlatformError`
+
+Thrown by `createJobPlatform` itself when the registry is misconfigured (for
+example, the same queue name declared twice) — a `JobPlatformError` means a
+programming mistake in the registry, never a failed job. Standard `Error`
+subclass: catch it with `instanceof JobPlatformError`.
+
+### Types
+
+Exported for typing your own helpers around `enqueue`/`defineWorker`:
+
+- **`JobLogger`** — the logging interface `createJobPlatform` expects;
+  satisfied by a pino logger or `console`.
+- **`JobOptions`** — the options `enqueue` accepts alongside `data` (pg-boss's
+  own send options, minus `db`, which the platform supplies for you).
+- **`QueueDefinition`** — one entry in a registry: `{ name, schema, global?,
+  options? }`.
+- **`QueueNameOf<D>`** — every queue name in a registry `D`, including
+  dead-letter targets.
+- **`QueuePayloadOf<D, Q>`** — the payload type for queue `Q` in registry `D`.
+- **`SendableOf<D>`** — the queue names `enqueue` accepts, with dead-letter
+  targets excluded; see [Dead-letter queues](#dead-letter-queues).
+- **`RegisteredWorker`** — the type `defineWorker` returns.
+- **`UserScoped`** — `{ userId: string }`, the inferred type of
+  `UserScopedSchema`.
+
+## Requirements
+
+- Node `>=22.12.0`
+- `pg-boss` `>=12.21.0 <13` (peer dependency)
+- `zod` `^4` (peer dependency)
+- A Postgres database (whatever `pg-boss` itself requires)
+- Zero runtime dependencies otherwise
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,291 @@
+import { PgBoss, Db, WorkOptions, JobWithMetadata } from 'pg-boss';
+import { z } from 'zod';
+
+/**
+ * Generic job-platform types. Nothing in this package knows anything about the
+ * application using it: no concrete queue, no configuration shape, no database
+ * type. A concrete instance is built by calling `createJobPlatform` with a
+ * queue registry and providers — see the README.
+ */
+/** The minimal logging surface the platform needs; a pino logger satisfies it. */
+type JobLogger = {
+    info(obj: Record<string, unknown>, msg: string): void;
+    warn(obj: Record<string, unknown>, msg: string): void;
+    error(obj: Record<string, unknown>, msg: string): void;
+};
+/**
+ * The acting user a job runs on behalf of — the identity a worker resolves
+ * credentials, tenancy or permissions from, and the one every job log line
+ * carries. A user-scoped queue's payload extends this; see `QueueDefinition`
+ * for the `global` opt-out used by system jobs that have no user.
+ *
+ * This lives in the payload (not pg-boss job metadata) because `data` is the
+ * only user-controlled channel pg-boss offers — and because the DLQ hop copies
+ * `data` verbatim, the acting user survives into dead-letter queues for free.
+ */
+declare const UserScopedSchema: z.ZodObject<{
+    userId: z.ZodString;
+}, z.core.$strip>;
+type UserScoped = z.infer<typeof UserScopedSchema>;
+type QueueOptions = NonNullable<Parameters<PgBoss["createQueue"]>[1]>;
+type QueueDefinitionBase = {
+    name: string;
+    /** pg-boss queue options. Omit entirely for a queue with nothing to configure. */
+    options?: Omit<QueueOptions, "name">;
+};
+/**
+ * A queue definition. By DEFAULT a queue is user-scoped: its payload schema
+ * must produce a `userId`, so forgetting the acting user on a new queue is a
+ * compile error rather than a runtime surprise discovered in a worker. System
+ * work that genuinely has no user on whose behalf it runs — cron sweeps,
+ * maintenance jobs — opts out explicitly with `global: true`.
+ *
+ * Because `enqueue`'s `data` parameter is derived from this schema
+ * (`QueuePayloadOf`), the constraint also makes it a compile error to enqueue
+ * without a user, or to drop the user across a chain hop.
+ *
+ * IMPORTANT: never store a registry in a variable annotated `QueueDefinition[]`
+ * or `readonly QueueDefinition[]`. Both spellings widen it, and widening costs
+ * two guarantees at once, silently:
+ *
+ * - `QueuePayloadOf` collapses to this type's base user-scoped shape, so
+ *   `enqueue` stops type-checking domain fields entirely.
+ * - `SendableOf` collapses to `string`, so the dead-letter exclusion disappears
+ *   and any queue name — including one that does not exist — compiles.
+ *
+ * Three spellings keep it precise: `defineQueues([...])`, an array literal
+ * passed straight into `createJobPlatform`, and `[...] satisfies
+ * QueueDefinition[]`. Prefer `defineQueues` — it checks each entry against this
+ * constraint without widening what it stores.
+ */
+type QueueDefinition = (QueueDefinitionBase & {
+    global?: false;
+    /** Zod schema for this queue's job payload — the single source of truth
+     * for both the compile-time payload type and the runtime boundary
+     * validation. Must carry the acting user (see `UserScopedSchema`). */
+    schema: z.ZodType<UserScoped>;
+}) | (QueueDefinitionBase & {
+    /** This queue's jobs run on behalf of no one — system work only. */
+    global: true;
+    /** Zod schema for this queue's job payload — the single source of truth
+     * for both the compile-time payload type and the runtime boundary
+     * validation. `object` because a pg-boss payload is always JSON. */
+    schema: z.ZodType<object>;
+});
+/** Every queue name in a registry. Broader than `SendableOf`: includes DLQs. */
+type QueueNameOf<D extends readonly QueueDefinition[]> = D[number]["name"];
+/**
+ * Payload type per queue, inferred from each declared Zod schema — the derived
+ * contract for `enqueue` and worker handlers, with no hand-written map to keep
+ * in sync. Modelled as an indexed access (not `Extract` + `z.infer`) so it
+ * resolves to a concrete object type for a generic `Q`, e.g. inside `enqueue`.
+ */
+type QueuePayloadMapOf<D extends readonly QueueDefinition[]> = {
+    [E in D[number] as E["name"]]: z.infer<E["schema"]>;
+};
+/**
+ * The `& object` states what is already true — a pg-boss payload is JSON — and
+ * is applied here rather than inside the map on purpose: with both `D` and `Q`
+ * generic the map lookup stays deferred, so only an intersection at this level
+ * keeps a payload provably assignable to `boss.send`'s `object` parameter.
+ */
+type QueuePayloadOf<D extends readonly QueueDefinition[], Q extends QueueNameOf<D>> = QueuePayloadMapOf<D>[Q] & object;
+/**
+ * Per-slot `options`, defaulting to `undefined` for a definition that omits it
+ * entirely. A plain `D[number]["options"]` indexed access does not work once
+ * `options` is optional: a tuple entry that omits the key altogether has no
+ * `options` property at all, and indexed access on a union requires every
+ * member to carry the key, so the lookup would fail to compile the moment any
+ * entry left `options` out. Distributing over `keyof D` (each tuple slot,
+ * rather than the merged `D[number]` union) sidesteps that — an entry without
+ * `options` just contributes `undefined` instead of breaking the type for
+ * every other entry.
+ */
+type OptionsTupleOf<D extends readonly QueueDefinition[]> = {
+    [K in keyof D]: "options" extends keyof D[K] ? D[K]["options"] : undefined;
+};
+/**
+ * Every dead-letter target named by some queue's `deadLetter` option. You never
+ * enqueue to a DLQ (pg-boss copies failed jobs into it automatically), so these
+ * are excluded from the enqueue-able set below.
+ */
+type DeadLetterOf<D extends readonly QueueDefinition[]> = Extract<OptionsTupleOf<D>[number], {
+    deadLetter: string;
+}>["deadLetter"];
+/**
+ * The queues application code may enqueue to: every defined queue minus the
+ * dead-letter targets. Derived, so declaring a new DLQ automatically keeps it
+ * off the enqueue surface.
+ */
+type SendableOf<D extends readonly QueueDefinition[]> = Exclude<QueueNameOf<D>, DeadLetterOf<D>>;
+type SendOptionsOf = NonNullable<Parameters<PgBoss["send"]>[2]>;
+/** pg-boss send options, minus `db` — the platform owns db threading. */
+type JobOptions = Omit<SendOptionsOf, "db">;
+/**
+ * A worker registered against a queue, type-erased for storage in a worker
+ * list. `defineWorker` binds the queue → payload → handler types; `register`
+ * closes over them so a heterogeneous worker list needs no shared handler type.
+ */
+type RegisteredWorker = {
+    queue: string;
+    register: (boss: PgBoss) => Promise<string>;
+};
+/**
+ * Declare a queue registry.
+ *
+ * The `const` type parameter preserves the literal tuple, so every derived type
+ * (`QueueNameOf`, `QueuePayloadOf`, `SendableOf`) stays precise. This is the
+ * recommended way to build a registry: the alternative spellings
+ * `const QUEUES: QueueDefinition[] = [...]` and
+ * `const QUEUES: readonly QueueDefinition[] = [...]` both type-check but widen,
+ * which collapses every payload to `UserScoped` AND collapses the enqueue-able
+ * name set to `string` — so domain fields stop being checked and the
+ * dead-letter guard quietly stops guarding. Calling a function instead of
+ * writing a type annotation makes that mistake unspellable.
+ */
+declare function defineQueues<const D extends readonly QueueDefinition[]>(defs: D): D;
+
+/**
+ * Pure factory — no caching, no process hooks, no config reading. Owning the
+ * boss lifecycle (singleton caching, shutdown hooks, reading connection
+ * settings) is the application's job.
+ *
+ * The `error` and `warning` handlers are the reason to prefer this over
+ * `new PgBoss(...)` directly: an unhandled pg-boss `error` event crashes the
+ * Node process.
+ */
+declare function createBoss(args: {
+    connectionString: string;
+    migrate: boolean;
+    max?: number;
+    /** Surfaces in `pg_stat_activity` — set it to something you can grep for. */
+    applicationName?: string;
+    /** Postgres schema pg-boss owns. Defaults to pg-boss's own default. */
+    schema?: string;
+    logger: JobLogger;
+}): PgBoss;
+
+/**
+ * Errors raised by the job platform itself — a misconfigured registry or a
+ * broken provider contract, not a job that failed. Always thrown at
+ * construction or boot, never from a job handler.
+ *
+ * A plain named subclass rather than a richer error type from some error
+ * framework: bosskit has zero runtime dependencies, and an error class is not
+ * worth acquiring one — nor worth forcing a dependency on callers who already
+ * have their own. (`instanceof` is reliable here — the package targets ES2022,
+ * so no prototype fixup is needed.)
+ */
+declare class JobPlatformError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Schedule declarations are generic over a registry's queue names, so a typo in
+ * a schedule target is a compile error. The sync itself lives on the platform
+ * (`applySchedules`) — it needs the registry's name type; this module holds the
+ * declaration shape and the pure diff.
+ */
+type ScheduleDefinition<Name extends string = string> = {
+    /** Queue that receives the scheduled job. */
+    queue: Name;
+    /** 5-field cron (minute precision) — pg-boss evaluates schedules every ~30s. */
+    cron: string;
+    /** Plain JSON-serializable data (no Dates/class instances) — it round-trips through jsonb. */
+    data?: object;
+    options?: {
+        /** IANA time zone; pg-boss defaults to UTC. */
+        tz?: string;
+        /** Unique key when one queue needs multiple schedules. */
+        key?: string;
+    };
+};
+/**
+ * Identity of an existing schedule row, all `applySchedules` needs to decide
+ * which stored schedules are no longer declared. `key` is `string | null` so a
+ * real `Schedule[]` from `boss.getSchedules()` (key is `''` when unset) and
+ * explicit-null test fixtures both assign here without a cast.
+ */
+type ExistingScheduleId = {
+    name: string;
+    key: string | null;
+};
+/**
+ * Pure: existing schedules that are no longer declared, so they can be
+ * unscheduled. We don't diff cron/data to decide what to *apply* — `boss.schedule`
+ * is an idempotent upsert and pg-boss derives fire times from the cron expression
+ * (not from `updated_on`), so re-applying an unchanged schedule is a cheap no-op
+ * with no effect on timing. Only removals need a diff.
+ */
+declare function schedulesToRemove(declared: ScheduleDefinition[], existing: ExistingScheduleId[]): Array<{
+    name: string;
+    key?: string;
+}>;
+
+/**
+ * Build a job platform bound to one queue registry.
+ *
+ * This is the package's only entry point, and the reason nothing inside it
+ * knows about the application using it. Everything application-shaped arrives
+ * through arguments:
+ *
+ * - `definitions` — the queue registry. Both the compile-time payload types and
+ *   the runtime boundary validation derive from it, so you declare each queue
+ *   exactly once.
+ * - `getBoss` — resolves a *started* pg-boss instance. A provider rather than an
+ *   instance because the boss is not started at module-evaluation time; you own
+ *   its creation, caching and config.
+ * - `getRuntime` — resolves whatever context handlers should receive (say,
+ *   `{ db, config }`). Its return type `R` is INFERRED, which is how handler
+ *   context gets typed without this package importing your `Db`/`Config`.
+ *   Resolved AT MOST ONCE for the life of the platform (see below), so anything
+ *   computed per call — a fresh request id, a timestamp — would be frozen at
+ *   the first value. Return a plain data object: handlers receive it via the
+ *   shallow spread `{ ...runtime, jobs }`, which drops a class instance's
+ *   prototype and with it every method on it.
+ * - `toBossDb` — adapts your database handle to pg-boss's `executeSql`
+ *   contract. Its parameter type `TDb` is INFERRED and becomes the `db` every
+ *   enqueue takes, so this package needs no ORM: pass one of pg-boss's own
+ *   adapters (`fromDrizzle`, `fromKnex`, `fromKysely`, `fromPrisma`,
+ *   `fromPglite`) or write three lines for any other client. ANNOTATE the
+ *   parameter — written as `(db) => ...` it infers `unknown`, and `enqueue`
+ *   then accepts any value at all as its `db`.
+ * - `logger` — the platform never reaches for a global logger.
+ *
+ * All three type parameters are inferred from the call, so you never write an
+ * explicit type argument. `const D` preserves the literal registry tuple, which
+ * is what keeps `QueuePayloadOf` precise (see the note on `QueueDefinition`).
+ */
+declare function createJobPlatform<const D extends readonly QueueDefinition[], R, TDb>(platform: {
+    definitions: D;
+    getBoss: () => Promise<PgBoss>;
+    getRuntime: () => Promise<R>;
+    toBossDb: (db: TDb) => Db;
+    logger: JobLogger;
+}): {
+    applySchedules: (boss: PgBoss, declared: ScheduleDefinition<QueueNameOf<D>>[]) => Promise<void>;
+    cancelJobs: (queue: QueueNameOf<D>, jobIds: string[]) => Promise<void>;
+    defineWorker: <Q extends QueueNameOf<D>>(w: {
+        queue: Q;
+        options?: Omit<WorkOptions, "includeMetadata">;
+        handler: (ctx: R & {
+            jobs: JobWithMetadata<QueuePayloadOf<D, Q>>[];
+        }) => Promise<void>;
+    }) => RegisteredWorker;
+    enqueue: <Q extends SendableOf<D> & QueueNameOf<D>>(args: {
+        db: TDb;
+        queue: Q;
+        data: QueuePayloadOf<D, Q>;
+        options?: JobOptions;
+    }) => Promise<string | null>;
+    enqueueWith: <Q extends SendableOf<D> & QueueNameOf<D>>(boss: PgBoss, args: {
+        db: TDb;
+        queue: Q;
+        data: QueuePayloadOf<D, Q>;
+        options?: JobOptions;
+    }) => Promise<string | null>;
+    ensureQueues: (boss: PgBoss) => Promise<void>;
+    schemaFor: <Q extends QueueNameOf<D>>(queue: Q) => z.ZodType<QueuePayloadOf<D, Q>>;
+};
+
+export { type JobLogger, type JobOptions, JobPlatformError, type QueueDefinition, type QueueNameOf, type QueuePayloadOf, type RegisteredWorker, type ScheduleDefinition, type SendableOf, type UserScoped, UserScopedSchema, createBoss, createJobPlatform, defineQueues, schedulesToRemove };

package/dist/index.js

@@ -0,0 +1,157 @@
+import { PgBoss } from 'pg-boss';
+import { z } from 'zod';
+
+// src/boss.ts
+function createBoss(args) {
+  const boss = new PgBoss({
+    application_name: args.applicationName ?? "bosskit",
+    connectionString: args.connectionString,
+    max: args.max ?? 5,
+    migrate: args.migrate,
+    schema: args.schema ?? "pgboss",
+    useListenNotify: true
+  });
+  boss.on("error", (err) => args.logger.error({ err }, "pg-boss error"));
+  boss.on("warning", (warning) => args.logger.warn({ warning }, "pg-boss warning"));
+  return boss;
+}
+
+// src/errors.ts
+var JobPlatformError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "JobPlatformError";
+  }
+};
+
+// src/schedules.ts
+function idOf(name, key) {
+  return `${name}::${key ?? ""}`;
+}
+function schedulesToRemove(declared, existing) {
+  const declaredIds = new Set(declared.map((d) => idOf(d.queue, d.options?.key)));
+  return existing.filter((e) => !declaredIds.has(idOf(e.name, e.key))).map((e) => !e.key ? { name: e.name } : { key: e.key, name: e.name });
+}
+var UserScopedSchema = z.object({ userId: z.string() });
+function defineQueues(defs) {
+  return defs;
+}
+
+// src/platform.ts
+function createJobPlatform(platform) {
+  const { definitions, getBoss, getRuntime, logger, toBossDb } = platform;
+  let runtimePromise;
+  function resolveRuntime() {
+    if (!runtimePromise) {
+      runtimePromise = getRuntime().catch((err) => {
+        runtimePromise = void 0;
+        throw err;
+      });
+    }
+    return runtimePromise;
+  }
+  const schemaByQueue = /* @__PURE__ */ new Map();
+  for (const d of definitions) {
+    if (schemaByQueue.has(d.name)) {
+      throw new JobPlatformError(`Queue "${d.name}" is declared more than once in the registry`);
+    }
+    schemaByQueue.set(d.name, d.schema);
+  }
+  function schemaFor(queue) {
+    const schema = schemaByQueue.get(queue);
+    if (!schema) {
+      throw new JobPlatformError(`Unknown queue "${queue}"`);
+    }
+    return schema;
+  }
+  async function enqueueWith(boss, args) {
+    const data = schemaFor(args.queue).parse(args.data);
+    return boss.send(args.queue, data, {
+      ...args.options,
+      db: toBossDb(args.db)
+    });
+  }
+  async function enqueue(args) {
+    return enqueueWith(await getBoss(), args);
+  }
+  async function cancelJobs(queue, jobIds) {
+    if (jobIds.length === 0) return;
+    const boss = await getBoss();
+    await boss.cancel(queue, jobIds).catch((err) => {
+      logger.warn({ err, jobIds, queue }, "job cancel failed (jobs may be settled)");
+    });
+  }
+  function defineWorker(w) {
+    return {
+      queue: w.queue,
+      register: async (boss) => {
+        const schema = schemaFor(w.queue);
+        const runtime = await resolveRuntime();
+        return boss.work(
+          w.queue,
+          { ...w.options, includeMetadata: true },
+          async (jobs) => {
+            const parsed = [];
+            for (const job of jobs) {
+              const data = schema.parse(job.data);
+              const actor = UserScopedSchema.safeParse(data);
+              logger.info(
+                {
+                  jobId: job.id,
+                  queue: w.queue,
+                  retryCount: job.retryCount,
+                  userId: actor.success ? actor.data.userId : void 0
+                },
+                "job received"
+              );
+              parsed.push({ ...job, data });
+            }
+            await w.handler({ ...runtime, jobs: parsed });
+          }
+        );
+      }
+    };
+  }
+  async function ensureQueues(boss) {
+    for (const def of definitions) {
+      const options = def.options ?? {};
+      const existing = await boss.getQueue(def.name);
+      if (existing) {
+        const { policy: _policy, partition: _partition, ...updatable } = options;
+        await boss.updateQueue(def.name, updatable);
+      } else {
+        await boss.createQueue(def.name, options);
+        logger.info({ queue: def.name }, "queue created");
+      }
+    }
+  }
+  async function applySchedules(boss, declared) {
+    for (const s of declared) {
+      await boss.schedule(s.queue, s.cron, s.data ?? null, s.options ?? {});
+    }
+    const toRemove = schedulesToRemove(declared, await boss.getSchedules());
+    for (const r of toRemove) {
+      if (r.key === void 0) {
+        await boss.unschedule(r.name);
+      } else {
+        await boss.unschedule(r.name, r.key);
+      }
+    }
+    if (declared.length > 0 || toRemove.length > 0) {
+      logger.info({ applied: declared.length, removed: toRemove }, "schedules synced");
+    }
+  }
+  return {
+    applySchedules,
+    cancelJobs,
+    defineWorker,
+    enqueue,
+    enqueueWith,
+    ensureQueues,
+    schemaFor
+  };
+}
+
+export { JobPlatformError, UserScopedSchema, createBoss, createJobPlatform, defineQueues, schedulesToRemove };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/boss.ts","../src/errors.ts","../src/schedules.ts","../src/types.ts","../src/platform.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { PgBoss } from \"pg-boss\";\nimport type { JobLogger } from \"./types\";\n\n/**\n * Pure factory — no caching, no process hooks, no config reading. Owning the\n * boss lifecycle (singleton caching, shutdown hooks, reading connection\n * settings) is the application's job.\n *\n * The `error` and `warning` handlers are the reason to prefer this over\n * `new PgBoss(...)` directly: an unhandled pg-boss `error` event crashes the\n * Node process.\n */\nexport function createBoss(args: {\n  connectionString: string;\n  migrate: boolean;\n  max?: number;\n  /** Surfaces in `pg_stat_activity` — set it to something you can grep for. */\n  applicationName?: string;\n  /** Postgres schema pg-boss owns. Defaults to pg-boss's own default. */\n  schema?: string;\n  logger: JobLogger;\n}): PgBoss {\n  const boss = new PgBoss({\n    application_name: args.applicationName ?? \"bosskit\",\n    connectionString: args.connectionString,\n    max: args.max ?? 5,\n    migrate: args.migrate,\n    schema: args.schema ?? \"pgboss\",\n    useListenNotify: true,\n  });\n  // Mandatory: an unhandled 'error' event would crash the Node process.\n  boss.on(\"error\", (err) => args.logger.error({ err }, \"pg-boss error\"));\n  boss.on(\"warning\", (warning) => args.logger.warn({ warning }, \"pg-boss warning\"));\n  return boss;\n}\n","/**\n * Errors raised by the job platform itself — a misconfigured registry or a\n * broken provider contract, not a job that failed. Always thrown at\n * construction or boot, never from a job handler.\n *\n * A plain named subclass rather than a richer error type from some error\n * framework: bosskit has zero runtime dependencies, and an error class is not\n * worth acquiring one — nor worth forcing a dependency on callers who already\n * have their own. (`instanceof` is reliable here — the package targets ES2022,\n * so no prototype fixup is needed.)\n */\nexport class JobPlatformError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"JobPlatformError\";\n  }\n}\n","/**\n * Schedule declarations are generic over a registry's queue names, so a typo in\n * a schedule target is a compile error. The sync itself lives on the platform\n * (`applySchedules`) — it needs the registry's name type; this module holds the\n * declaration shape and the pure diff.\n */\nexport type ScheduleDefinition<Name extends string = string> = {\n  /** Queue that receives the scheduled job. */\n  queue: Name;\n  /** 5-field cron (minute precision) — pg-boss evaluates schedules every ~30s. */\n  cron: string;\n  /** Plain JSON-serializable data (no Dates/class instances) — it round-trips through jsonb. */\n  data?: object;\n  options?: {\n    /** IANA time zone; pg-boss defaults to UTC. */\n    tz?: string;\n    /** Unique key when one queue needs multiple schedules. */\n    key?: string;\n  };\n};\n\n/**\n * Identity of an existing schedule row, all `applySchedules` needs to decide\n * which stored schedules are no longer declared. `key` is `string | null` so a\n * real `Schedule[]` from `boss.getSchedules()` (key is `''` when unset) and\n * explicit-null test fixtures both assign here without a cast.\n */\ntype ExistingScheduleId = { name: string; key: string | null };\n\n/** Stable identity for a schedule: same queue + key = same schedule (empty/null/undefined key all normalize together). */\nfunction idOf(name: string, key: string | null | undefined): string {\n  return `${name}::${key ?? \"\"}`;\n}\n\n/**\n * Pure: existing schedules that are no longer declared, so they can be\n * unscheduled. We don't diff cron/data to decide what to *apply* — `boss.schedule`\n * is an idempotent upsert and pg-boss derives fire times from the cron expression\n * (not from `updated_on`), so re-applying an unchanged schedule is a cheap no-op\n * with no effect on timing. Only removals need a diff.\n */\nexport function schedulesToRemove(\n  declared: ScheduleDefinition[],\n  existing: ExistingScheduleId[]\n): Array<{ name: string; key?: string }> {\n  const declaredIds = new Set(declared.map((d) => idOf(d.queue, d.options?.key)));\n  return existing\n    .filter((e) => !declaredIds.has(idOf(e.name, e.key)))\n    .map((e) => (!e.key ? { name: e.name } : { key: e.key, name: e.name }));\n}\n","import type { PgBoss } from \"pg-boss\";\nimport { z } from \"zod\";\n\n/**\n * Generic job-platform types. Nothing in this package knows anything about the\n * application using it: no concrete queue, no configuration shape, no database\n * type. A concrete instance is built by calling `createJobPlatform` with a\n * queue registry and providers — see the README.\n */\n\n/** The minimal logging surface the platform needs; a pino logger satisfies it. */\nexport type JobLogger = {\n  info(obj: Record<string, unknown>, msg: string): void;\n  warn(obj: Record<string, unknown>, msg: string): void;\n  error(obj: Record<string, unknown>, msg: string): void;\n};\n\n/**\n * The acting user a job runs on behalf of — the identity a worker resolves\n * credentials, tenancy or permissions from, and the one every job log line\n * carries. A user-scoped queue's payload extends this; see `QueueDefinition`\n * for the `global` opt-out used by system jobs that have no user.\n *\n * This lives in the payload (not pg-boss job metadata) because `data` is the\n * only user-controlled channel pg-boss offers — and because the DLQ hop copies\n * `data` verbatim, the acting user survives into dead-letter queues for free.\n */\nexport const UserScopedSchema = z.object({ userId: z.string() });\nexport type UserScoped = z.infer<typeof UserScopedSchema>;\n\ntype QueueOptions = NonNullable<Parameters<PgBoss[\"createQueue\"]>[1]>;\n\ntype QueueDefinitionBase = {\n  name: string;\n  /** pg-boss queue options. Omit entirely for a queue with nothing to configure. */\n  options?: Omit<QueueOptions, \"name\">;\n};\n\n/**\n * A queue definition. By DEFAULT a queue is user-scoped: its payload schema\n * must produce a `userId`, so forgetting the acting user on a new queue is a\n * compile error rather than a runtime surprise discovered in a worker. System\n * work that genuinely has no user on whose behalf it runs — cron sweeps,\n * maintenance jobs — opts out explicitly with `global: true`.\n *\n * Because `enqueue`'s `data` parameter is derived from this schema\n * (`QueuePayloadOf`), the constraint also makes it a compile error to enqueue\n * without a user, or to drop the user across a chain hop.\n *\n * IMPORTANT: never store a registry in a variable annotated `QueueDefinition[]`\n * or `readonly QueueDefinition[]`. Both spellings widen it, and widening costs\n * two guarantees at once, silently:\n *\n * - `QueuePayloadOf` collapses to this type's base user-scoped shape, so\n *   `enqueue` stops type-checking domain fields entirely.\n * - `SendableOf` collapses to `string`, so the dead-letter exclusion disappears\n *   and any queue name — including one that does not exist — compiles.\n *\n * Three spellings keep it precise: `defineQueues([...])`, an array literal\n * passed straight into `createJobPlatform`, and `[...] satisfies\n * QueueDefinition[]`. Prefer `defineQueues` — it checks each entry against this\n * constraint without widening what it stores.\n */\nexport type QueueDefinition =\n  | (QueueDefinitionBase & {\n      global?: false;\n      /** Zod schema for this queue's job payload — the single source of truth\n       * for both the compile-time payload type and the runtime boundary\n       * validation. Must carry the acting user (see `UserScopedSchema`). */\n      schema: z.ZodType<UserScoped>;\n    })\n  | (QueueDefinitionBase & {\n      /** This queue's jobs run on behalf of no one — system work only. */\n      global: true;\n      /** Zod schema for this queue's job payload — the single source of truth\n       * for both the compile-time payload type and the runtime boundary\n       * validation. `object` because a pg-boss payload is always JSON. */\n      schema: z.ZodType<object>;\n    });\n\n/** Every queue name in a registry. Broader than `SendableOf`: includes DLQs. */\nexport type QueueNameOf<D extends readonly QueueDefinition[]> = D[number][\"name\"];\n\n/**\n * Payload type per queue, inferred from each declared Zod schema — the derived\n * contract for `enqueue` and worker handlers, with no hand-written map to keep\n * in sync. Modelled as an indexed access (not `Extract` + `z.infer`) so it\n * resolves to a concrete object type for a generic `Q`, e.g. inside `enqueue`.\n */\ntype QueuePayloadMapOf<D extends readonly QueueDefinition[]> = {\n  [E in D[number] as E[\"name\"]]: z.infer<E[\"schema\"]>;\n};\n/**\n * The `& object` states what is already true — a pg-boss payload is JSON — and\n * is applied here rather than inside the map on purpose: with both `D` and `Q`\n * generic the map lookup stays deferred, so only an intersection at this level\n * keeps a payload provably assignable to `boss.send`'s `object` parameter.\n */\nexport type QueuePayloadOf<\n  D extends readonly QueueDefinition[],\n  Q extends QueueNameOf<D>,\n> = QueuePayloadMapOf<D>[Q] & object;\n\n/**\n * Per-slot `options`, defaulting to `undefined` for a definition that omits it\n * entirely. A plain `D[number][\"options\"]` indexed access does not work once\n * `options` is optional: a tuple entry that omits the key altogether has no\n * `options` property at all, and indexed access on a union requires every\n * member to carry the key, so the lookup would fail to compile the moment any\n * entry left `options` out. Distributing over `keyof D` (each tuple slot,\n * rather than the merged `D[number]` union) sidesteps that — an entry without\n * `options` just contributes `undefined` instead of breaking the type for\n * every other entry.\n */\ntype OptionsTupleOf<D extends readonly QueueDefinition[]> = {\n  [K in keyof D]: \"options\" extends keyof D[K] ? D[K][\"options\"] : undefined;\n};\n\n/**\n * Every dead-letter target named by some queue's `deadLetter` option. You never\n * enqueue to a DLQ (pg-boss copies failed jobs into it automatically), so these\n * are excluded from the enqueue-able set below.\n */\ntype DeadLetterOf<D extends readonly QueueDefinition[]> = Extract<\n  OptionsTupleOf<D>[number],\n  { deadLetter: string }\n>[\"deadLetter\"];\n\n/**\n * The queues application code may enqueue to: every defined queue minus the\n * dead-letter targets. Derived, so declaring a new DLQ automatically keeps it\n * off the enqueue surface.\n */\nexport type SendableOf<D extends readonly QueueDefinition[]> = Exclude<\n  QueueNameOf<D>,\n  DeadLetterOf<D>\n>;\n\ntype SendOptionsOf = NonNullable<Parameters<PgBoss[\"send\"]>[2]>;\n/** pg-boss send options, minus `db` — the platform owns db threading. */\nexport type JobOptions = Omit<SendOptionsOf, \"db\">;\n\n/**\n * A worker registered against a queue, type-erased for storage in a worker\n * list. `defineWorker` binds the queue → payload → handler types; `register`\n * closes over them so a heterogeneous worker list needs no shared handler type.\n */\nexport type RegisteredWorker = {\n  queue: string;\n  register: (boss: PgBoss) => Promise<string>;\n};\n\n/**\n * Declare a queue registry.\n *\n * The `const` type parameter preserves the literal tuple, so every derived type\n * (`QueueNameOf`, `QueuePayloadOf`, `SendableOf`) stays precise. This is the\n * recommended way to build a registry: the alternative spellings\n * `const QUEUES: QueueDefinition[] = [...]` and\n * `const QUEUES: readonly QueueDefinition[] = [...]` both type-check but widen,\n * which collapses every payload to `UserScoped` AND collapses the enqueue-able\n * name set to `string` — so domain fields stop being checked and the\n * dead-letter guard quietly stops guarding. Calling a function instead of\n * writing a type annotation makes that mistake unspellable.\n */\nexport function defineQueues<const D extends readonly QueueDefinition[]>(defs: D): D {\n  return defs;\n}\n","import type { JobWithMetadata, PgBoss, Db as PgBossDb, WorkOptions } from \"pg-boss\";\nimport type { z } from \"zod\";\nimport { JobPlatformError } from \"./errors\";\nimport { type ScheduleDefinition, schedulesToRemove } from \"./schedules\";\nimport {\n  type JobLogger,\n  type JobOptions,\n  type QueueDefinition,\n  type QueueNameOf,\n  type QueuePayloadOf,\n  type RegisteredWorker,\n  type SendableOf,\n  UserScopedSchema,\n} from \"./types\";\n\n/**\n * Build a job platform bound to one queue registry.\n *\n * This is the package's only entry point, and the reason nothing inside it\n * knows about the application using it. Everything application-shaped arrives\n * through arguments:\n *\n * - `definitions` — the queue registry. Both the compile-time payload types and\n *   the runtime boundary validation derive from it, so you declare each queue\n *   exactly once.\n * - `getBoss` — resolves a *started* pg-boss instance. A provider rather than an\n *   instance because the boss is not started at module-evaluation time; you own\n *   its creation, caching and config.\n * - `getRuntime` — resolves whatever context handlers should receive (say,\n *   `{ db, config }`). Its return type `R` is INFERRED, which is how handler\n *   context gets typed without this package importing your `Db`/`Config`.\n *   Resolved AT MOST ONCE for the life of the platform (see below), so anything\n *   computed per call — a fresh request id, a timestamp — would be frozen at\n *   the first value. Return a plain data object: handlers receive it via the\n *   shallow spread `{ ...runtime, jobs }`, which drops a class instance's\n *   prototype and with it every method on it.\n * - `toBossDb` — adapts your database handle to pg-boss's `executeSql`\n *   contract. Its parameter type `TDb` is INFERRED and becomes the `db` every\n *   enqueue takes, so this package needs no ORM: pass one of pg-boss's own\n *   adapters (`fromDrizzle`, `fromKnex`, `fromKysely`, `fromPrisma`,\n *   `fromPglite`) or write three lines for any other client. ANNOTATE the\n *   parameter — written as `(db) => ...` it infers `unknown`, and `enqueue`\n *   then accepts any value at all as its `db`.\n * - `logger` — the platform never reaches for a global logger.\n *\n * All three type parameters are inferred from the call, so you never write an\n * explicit type argument. `const D` preserves the literal registry tuple, which\n * is what keeps `QueuePayloadOf` precise (see the note on `QueueDefinition`).\n */\nexport function createJobPlatform<const D extends readonly QueueDefinition[], R, TDb>(platform: {\n  definitions: D;\n  getBoss: () => Promise<PgBoss>;\n  getRuntime: () => Promise<R>;\n  toBossDb: (db: TDb) => PgBossDb;\n  logger: JobLogger;\n}) {\n  const { definitions, getBoss, getRuntime, logger, toBossDb } = platform;\n\n  /**\n   * Resolve the runtime at most once, lazily, on the first worker registration.\n   * `register` runs per worker, and a provider that allocated a connection pool\n   * per call would quietly open one per worker. The memo is cleared only when\n   * the promise rejects, so a transient failure at boot doesn't poison a later\n   * retry; a successful resolution is kept for the life of the platform.\n   */\n  let runtimePromise: Promise<R> | undefined;\n  function resolveRuntime(): Promise<R> {\n    if (!runtimePromise) {\n      runtimePromise = getRuntime().catch((err: unknown) => {\n        runtimePromise = undefined;\n        throw err;\n      });\n    }\n    return runtimePromise;\n  }\n\n  type Name = QueueNameOf<D>;\n  type Sendable = SendableOf<D>;\n  type Payload<Q extends Name> = QueuePayloadOf<D, Q>;\n\n  // Runtime name → schema lookup, built from the definitions. Duplicate names\n  // are rejected rather than last-write-wins: the payload TYPE for a repeated\n  // name is the union of both schemas, but only one schema would do the\n  // validating, so half the payloads would be checked against the wrong shape.\n  // The type system can't catch this (a duplicated key just merges), so the\n  // registry is verified here, once, at construction.\n  const schemaByQueue = new Map<string, QueueDefinition[\"schema\"]>();\n  for (const d of definitions) {\n    if (schemaByQueue.has(d.name)) {\n      throw new JobPlatformError(`Queue \"${d.name}\" is declared more than once in the registry`);\n    }\n    schemaByQueue.set(d.name, d.schema);\n  }\n\n  /**\n   * Look up a queue's payload schema at runtime, typed so `.parse()` returns the\n   * queue's payload. Used when validating outgoing (enqueue) and incoming\n   * (worker) payloads — both boundaries validate from this one schema.\n   *\n   * The single cast is unavoidable: a runtime lookup can't be correlated to the\n   * compile-time payload type. It is sound because the map is built directly\n   * from `definitions`, whose entry for `queue` carries exactly this schema.\n   *\n   * The miss is still checked. On the inferred path every name is present, but\n   * `schemaFor` is exported and a caller whose registry type has widened to\n   * `QueueDefinition[]` can reach it with any string. Without the guard that\n   * surfaces as `Cannot read properties of undefined (reading 'parse')` from\n   * somewhere else entirely.\n   */\n  function schemaFor<Q extends Name>(queue: Q): z.ZodType<Payload<Q>> {\n    const schema = schemaByQueue.get(queue);\n    if (!schema) {\n      throw new JobPlatformError(`Unknown queue \"${queue}\"`);\n    }\n    return schema as z.ZodType<Payload<Q>>;\n  }\n\n  /**\n   * Core enqueue, parameterized by boss instance for tests.\n   * `db` is whatever `toBossDb` accepts — typically a pool handle or a\n   * transaction handle. Pass the transaction to make job creation atomic with\n   * your domain writes; the queue NOTIFY fires on commit.\n   *\n   * The payload is validated against the queue's schema before sending —\n   * defense in depth: the worker validates again on the way out, both from the\n   * one schema.\n   */\n  async function enqueueWith<Q extends Sendable & Name>(\n    boss: PgBoss,\n    args: { db: TDb; queue: Q; data: Payload<Q>; options?: JobOptions }\n  ): Promise<string | null> {\n    const data = schemaFor(args.queue).parse(args.data);\n    return boss.send(args.queue, data, {\n      ...args.options,\n      db: toBossDb(args.db),\n    });\n  }\n\n  /**\n   * The one sanctioned way for application code to create a job.\n   * Never call boss.send() directly. Payloads are thin references and must\n   * never contain credentials — job rows persist in the database for days.\n   */\n  async function enqueue<Q extends Sendable & Name>(args: {\n    db: TDb;\n    queue: Q;\n    data: Payload<Q>;\n    options?: JobOptions;\n  }): Promise<string | null> {\n    return enqueueWith(await getBoss(), args);\n  }\n\n  /**\n   * Cancel jobs on a queue by id (e.g. when their domain record is cancelled).\n   * Best-effort: pg-boss updates only cancellable jobs, so already-settled ids\n   * are a no-op. Cancelling stops a queued job from starting and prevents a\n   * retry of an active one — it does NOT abort a job already running on a\n   * worker; interrupt that in-process.\n   */\n  async function cancelJobs(queue: Name, jobIds: string[]): Promise<void> {\n    if (jobIds.length === 0) return;\n    const boss = await getBoss();\n    await boss.cancel(queue, jobIds).catch((err: unknown) => {\n      logger.warn({ err, jobIds, queue }, \"job cancel failed (jobs may be settled)\");\n    });\n  }\n\n  /**\n   * Define a worker for a queue. The handler receives the resolved runtime\n   * (`R`, inferred from `getRuntime`) spread alongside the validated, typed\n   * jobs — so handlers never open a database connection or parse payloads\n   * themselves. The spread is shallow: a runtime that is a class instance\n   * arrives without its prototype, so keep it plain data.\n   *\n   * Each job's payload is parsed through the queue's schema at this boundary and\n   * the handler receives the PARSED jobs, so coercions and defaults declared in\n   * the schema are already applied when it runs. A payload that fails validation\n   * throws, so the job fails → pg-boss retries → dead-letters, like any other\n   * handler error; parsing is per batch, so one bad payload fails the whole\n   * batch it arrived in. Every job is also logged here with its queue, id, retry\n   * count and acting user, so no handler has to remember to trace who a job is\n   * for.\n   */\n  function defineWorker<Q extends Name>(w: {\n    queue: Q;\n    options?: Omit<WorkOptions, \"includeMetadata\">;\n    handler: (ctx: R & { jobs: JobWithMetadata<Payload<Q>>[] }) => Promise<void>;\n  }): RegisteredWorker {\n    return {\n      queue: w.queue,\n      register: async (boss) => {\n        // Resolved at registration (boot) time, so neither depends on module\n        // init order.\n        const schema = schemaFor(w.queue);\n        const runtime = await resolveRuntime();\n        // boss.work uses `const O`, so the literal includeMetadata:true survives\n        // inference → JobWithMetadata handler; ReqData infers from the annotated\n        // `jobs` param. No explicit type args, no cast.\n        return boss.work(\n          w.queue,\n          { ...w.options, includeMetadata: true },\n          async (jobs: JobWithMetadata<Payload<Q>>[]) => {\n            // The handler is handed the PARSED jobs, not the raw ones. `data`\n            // arrives as jsonb, and the handler's type is the schema's OUTPUT\n            // type — so a `z.coerce.date()` field must reach it as a Date and a\n            // `.default()` field must be filled in, not left undefined.\n            const parsed: JobWithMetadata<Payload<Q>>[] = [];\n            for (const job of jobs) {\n              const data = schema.parse(job.data);\n              // Uniform actor trace for every queue. safeParse (not a cast) so\n              // this also works for `global` queues, whose payloads carry no user.\n              const actor = UserScopedSchema.safeParse(data);\n              logger.info(\n                {\n                  jobId: job.id,\n                  queue: w.queue,\n                  retryCount: job.retryCount,\n                  userId: actor.success ? actor.data.userId : undefined,\n                },\n                \"job received\"\n              );\n              parsed.push({ ...job, data });\n            }\n            await w.handler({ ...runtime, jobs: parsed });\n          }\n        );\n      },\n    };\n  }\n\n  /**\n   * Create missing queues; update options on existing ones (policy/partition are\n   * immutable in pg-boss). Note: pg-boss's `update_queue` COALESCEs unspecified\n   * options to their current values, so removing an option from a definition\n   * here does not reset it to default on an already-created queue — that needs\n   * a fresh queue or manual intervention.\n   */\n  async function ensureQueues(boss: PgBoss): Promise<void> {\n    for (const def of definitions) {\n      // Widen the `as const` options back to the mutable, all-optional pg-boss\n      // shape so we can strip the immutable fields without narrowing errors.\n      // Definitions with nothing to configure omit `options` entirely.\n      const options: Omit<\n        NonNullable<Parameters<PgBoss[\"createQueue\"]>[1]>,\n        \"name\"\n      > = def.options ?? {};\n      const existing = await boss.getQueue(def.name);\n      if (existing) {\n        const { policy: _policy, partition: _partition, ...updatable } = options;\n        await boss.updateQueue(def.name, updatable);\n      } else {\n        await boss.createQueue(def.name, options);\n        logger.info({ queue: def.name }, \"queue created\");\n      }\n    }\n  }\n\n  /** Idempotent sync: upsert every declared schedule, unschedule the rest. */\n  async function applySchedules(boss: PgBoss, declared: ScheduleDefinition<Name>[]): Promise<void> {\n    for (const s of declared) {\n      await boss.schedule(s.queue, s.cron, s.data ?? null, s.options ?? {});\n    }\n    const toRemove = schedulesToRemove(declared, await boss.getSchedules());\n    for (const r of toRemove) {\n      if (r.key === undefined) {\n        await boss.unschedule(r.name);\n      } else {\n        await boss.unschedule(r.name, r.key);\n      }\n    }\n    // Log only when there's something to report (silent on the common empty\n    // case). `applied` is a count — it's every declared schedule on every boot,\n    // so the identities aren't news — but list the removed ones: a schedule\n    // being turned off is the rare, notable event and you want to see which.\n    if (declared.length > 0 || toRemove.length > 0) {\n      logger.info({ applied: declared.length, removed: toRemove }, \"schedules synced\");\n    }\n  }\n\n  return {\n    applySchedules,\n    cancelJobs,\n    defineWorker,\n    enqueue,\n    enqueueWith,\n    ensureQueues,\n    schemaFor,\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "bosskit",
+  "version": "0.1.0",
+  "description": "Type-safe, user-scoped job queues for pg-boss, powered by Zod.",
+  "license": "MIT",
+  "author": "Kenny Williams",
+  "type": "module",
+  "packageManager": "pnpm@10.29.1",
+  "sideEffects": false,
+  "files": ["dist", "README.md", "LICENSE"],
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "prepublishOnly": "pnpm check && pnpm typecheck && pnpm test && pnpm build"
+  },
+  "homepage": "https://github.com/kennyjwilli/bosskit#readme",
+  "bugs": {
+    "url": "https://github.com/kennyjwilli/bosskit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kennyjwilli/bosskit.git"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "peerDependencies": {
+    "pg-boss": ">=12.21.0 <13",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.20.1",
+    "drizzle-orm": "^0.45.2",
+    "pg-boss": "^12.26.3",
+    "postgres": "^3.4.9",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9",
+    "zod": "^4.4.3"
+  },
+  "keywords": ["pg-boss", "postgres", "jobs", "queue", "worker", "zod", "type-safe", "multi-tenant"]
+}