pipework 0.251.0 → 0.252.1

package/src/async/jobs/cron.ts

@@ -0,0 +1,179 @@
+import { ValidationError } from '../../core/errors/index.js'
+
+/** Parsed cron schedule — arrays of valid minutes, hours, days, months, weekdays. */
+export interface CronSchedule {
+  readonly minutes: readonly number[]
+  readonly hours: readonly number[]
+  readonly daysOfMonth: readonly number[]
+  readonly months: readonly number[]
+  readonly daysOfWeek: readonly number[]
+}
+
+const FIELD_RANGES: readonly [number, number][] = [
+  [0, 59],   // minute
+  [0, 23],   // hour
+  [1, 31],   // day of month
+  [1, 12],   // month
+  [0, 6],    // day of week (0=Sun)
+]
+
+export function parseCron(expression: string): CronSchedule {
+  const parts = expression.trim().split(/\s+/)
+  if (parts.length !== 5) {
+    throw new ValidationError(
+      `Invalid cron expression "${expression}": expected 5 fields (minute hour day month weekday), got ${parts.length}`,
+    )
+  }
+
+  const [minutes, hours, daysOfMonth, months, daysOfWeek] = parts as [string, string, string, string, string]
+  return {
+    minutes: parseField(minutes, FIELD_RANGES[0]!, 'minute'),
+    hours: parseField(hours, FIELD_RANGES[1]!, 'hour'),
+    daysOfMonth: parseField(daysOfMonth, FIELD_RANGES[2]!, 'day-of-month'),
+    months: parseField(months, FIELD_RANGES[3]!, 'month'),
+    daysOfWeek: parseField(daysOfWeek, FIELD_RANGES[4]!, 'day-of-week'),
+  }
+}
+
+function parseField(field: string, [min, max]: [number, number], name: string): number[] {
+  const values = new Set<number>()
+
+  for (const part of field.split(',')) {
+    const stepMatch = part.match(/^(.+)\/(\d+)$/)
+    const step = stepMatch ? parseInt(stepMatch[2]!, 10) : null
+    const rangePart = stepMatch ? stepMatch[1]! : part
+
+    if (step !== null && (step < 1 || step > max)) {
+      throw new ValidationError(`Invalid cron ${name}: step "${step}" out of range`)
+    }
+
+    if (rangePart === '*') {
+      for (let i = min; i <= max; i += (step ?? 1)) {
+        values.add(i)
+      }
+    } else if (rangePart.includes('-')) {
+      const [startStr, endStr] = rangePart.split('-') as [string, string]
+      const start = parseInt(startStr, 10)
+      const end = parseInt(endStr, 10)
+      if (Number.isNaN(start) || Number.isNaN(end) || start < min || end > max || start > end) {
+        throw new ValidationError(`Invalid cron ${name}: range "${rangePart}" out of bounds (${min}-${max})`)
+      }
+      for (let i = start; i <= end; i += (step ?? 1)) {
+        values.add(i)
+      }
+    } else {
+      const val = parseInt(rangePart, 10)
+      if (Number.isNaN(val) || val < min || val > max) {
+        throw new ValidationError(`Invalid cron ${name}: value "${rangePart}" out of range (${min}-${max})`)
+      }
+      if (step !== null) {
+        for (let i = val; i <= max; i += step) {
+          values.add(i)
+        }
+      } else {
+        values.add(val)
+      }
+    }
+  }
+
+  return [...values].sort((a, b) => a - b)
+}
+
+export function nextTick(schedule: CronSchedule, after: Date, timezone?: string): Date {
+  const tz = timezone ?? 'UTC'
+  const formatter = new Intl.DateTimeFormat('en-US', {
+    timeZone: tz,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  })
+
+  const parts = extractParts(formatter, after)
+  let year = parts.year
+  let month = parts.month
+  let day = parts.day
+  let hour = parts.hour
+  let minute = parts.minute + 1
+
+  for (let guard = 0; guard < 5 * 366; guard++) {
+    if (minute > 59) { minute = 0; hour++ }
+    if (hour > 23) { hour = 0; day++ }
+    const dim = getDaysInMonth(year, month)
+    if (day > dim) { day = 1; month++ }
+    if (month > 12) { month = 1; year++ }
+
+    if (!schedule.months.includes(month)) {
+      month++; day = schedule.daysOfMonth[0]!; hour = schedule.hours[0]!; minute = schedule.minutes[0]!
+      continue
+    }
+
+    if (!schedule.daysOfMonth.includes(day)) {
+      day++; hour = schedule.hours[0]!; minute = schedule.minutes[0]!
+      continue
+    }
+
+    const dow = getDayOfWeekForDate(year, month, day)
+    if (!schedule.daysOfWeek.includes(dow)) {
+      day++; hour = schedule.hours[0]!; minute = schedule.minutes[0]!
+      continue
+    }
+
+    if (!schedule.hours.includes(hour)) {
+      const nextHour = schedule.hours.find(h => h > hour)
+      if (nextHour !== undefined) {
+        hour = nextHour; minute = schedule.minutes[0]!
+      } else {
+        day++; hour = schedule.hours[0]!; minute = schedule.minutes[0]!
+      }
+      continue
+    }
+
+    if (!schedule.minutes.includes(minute)) {
+      const nextMin = schedule.minutes.find(m => m >= minute)
+      if (nextMin !== undefined) {
+        minute = nextMin
+      } else {
+        hour++; minute = schedule.minutes[0]!
+      }
+      continue
+    }
+
+    return buildDate(tz, year, month, day, hour, minute)
+  }
+
+  throw new Error('Could not find next cron tick within search window')
+}
+
+function extractParts(formatter: Intl.DateTimeFormat, date: Date): { year: number; month: number; day: number; hour: number; minute: number } {
+  const resolved = formatter.formatToParts(date)
+  const get = (type: Intl.DateTimeFormatPartTypes) => parseInt(resolved.find(p => p.type === type)!.value, 10)
+  return { year: get('year'), month: get('month'), day: get('day'), hour: get('hour'), minute: get('minute') }
+}
+
+function getDayOfWeekForDate(year: number, month: number, day: number): number {
+  return new Date(Date.UTC(year, month - 1, day, 12, 0, 0)).getUTCDay()
+}
+
+function getDaysInMonth(year: number, month: number): number {
+  return new Date(year, month, 0).getDate()
+}
+
+function buildDate(tz: string, year: number, month: number, day: number, hour: number, minute: number): Date {
+  if (tz === 'UTC') {
+    return new Date(Date.UTC(year, month - 1, day, hour, minute, 0, 0))
+  }
+  const iso = `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}T${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}:00`
+  const formatter = new Intl.DateTimeFormat('en-US', { timeZone: tz, timeZoneName: 'longOffset' })
+  const refParts = formatter.formatToParts(new Date(iso + 'Z'))
+  const tzPart = refParts.find(p => p.type === 'timeZoneName')?.value ?? '+00:00'
+  const offsetMatch = tzPart.match(/GMT([+-]\d{1,2}):?(\d{2})?/)
+  if (!offsetMatch) return new Date(iso + 'Z')
+  const offsetHours = parseInt(offsetMatch[1]!, 10)
+  const offsetMinutes = parseInt(offsetMatch[2] ?? '0', 10)
+  const totalOffsetMs = (offsetHours * 60 + (offsetHours < 0 ? -offsetMinutes : offsetMinutes)) * 60_000
+  return new Date(new Date(iso + 'Z').getTime() - totalOffsetMs)
+}

package/src/async/jobs/errors.ts

@@ -0,0 +1,56 @@
+import { PipeworkError } from '../../core/errors/base.js'
+
+/**
+ * Thrown by `jobs.execute` when the caller's `signal` aborts before the handler
+ * returns. `name` is `'AbortError'` so the standard `err.name === 'AbortError'`
+ * check works; `code` stays pipework's `JOB_ABORTED`.
+ *
+ * Aborting with an `Error` as the reason rejects with that error instead — the
+ * worker uses this to keep its own job-timeout message.
+ */
+export class JobAbortedError extends PipeworkError {
+  readonly code = 'JOB_ABORTED' as const
+  readonly httpStatus = 499 as const
+
+  constructor(jobLabel: string, reason?: unknown) {
+    super(
+      `[pipework] Job ${jobLabel} was aborted by its caller's signal.\n\n` +
+      '  The handler was still running; its transaction was rolled back and its\n' +
+      '  connection released. An in-flight query was cancelled on the server, but a\n' +
+      '  handler that ignores the cancellation keeps running until it returns.\n',
+      reason === undefined ? { jobLabel } : { jobLabel, reason },
+    )
+    this.name = 'AbortError'
+  }
+}
+
+/**
+ * Thrown by a job handler to end the attempt as "try again later": the job goes
+ * back to pending after `delayMs` (the queue's backoff, at least a second, when
+ * unset) and the attempt is not counted. Build it with `jobs.later(...)`.
+ */
+export class JobLaterError extends PipeworkError {
+  readonly code = 'JOB_LATER' as const
+  readonly httpStatus = 503 as const
+  readonly delayMs: number | undefined
+
+  constructor(message: string, opts: { delayMs?: number; cause?: unknown } = {}) {
+    super(message, opts.cause === undefined ? {} : { cause: opts.cause })
+    this.name = 'JobLaterError'
+    this.delayMs = opts.delayMs
+  }
+}
+
+/**
+ * Thrown by a job handler to end the attempt as a final failure: the job is
+ * dead-lettered now, whatever attempts remain. Build it with `jobs.permanent(...)`.
+ */
+export class JobPermanentError extends PipeworkError {
+  readonly code = 'JOB_PERMANENT' as const
+  readonly httpStatus = 500 as const
+
+  constructor(message: string, opts: { cause?: unknown } = {}) {
+    super(message, opts.cause === undefined ? {} : { cause: opts.cause })
+    this.name = 'JobPermanentError'
+  }
+}

package/src/async/jobs/exclusion.ts

@@ -0,0 +1,117 @@
+// Cross-job exclusion gate for the claim query.
+//
+// A job "participates" in exclusion when its array column is non-NULL or its
+// blocks-all flag is true. Against the concurrent set R (claimed/running jobs,
+// tenant-scoped when a tenant column is configured), a pending candidate is
+// claimable when:
+//   - it does not participate: always claimable, and it never blocks others
+//   - it is blocks-all: R contains no participating job
+//   - it carries an array: R contains no blocks-all job and no job whose
+//     array overlaps (&&) the candidate's
+//
+// Two concurrent workers can evaluate these NOT EXISTS checks against the same
+// MVCC snapshot and both pass (write skew) — the claim query must run under
+// SERIALIZABLE; queue.ts handles that.
+
+import { assertValidIdentifier, quoteIdentifier } from '../../data/db/identifiers.js'
+import { QUEUE_BASE_COLUMNS } from './table.js'
+
+/** Cross-job exclusion config — names the consumer's conflict columns; the mechanism is pipework's. */
+export interface ExclusionConfig {
+  /** Array column — two jobs whose arrays overlap (`&&`) are mutually exclusive. */
+  readonly arrayColumn?: string
+  /** Element type of `arrayColumn`. Default `'uuid'`. */
+  readonly arrayElementType?: 'uuid' | 'text'
+  /** Boolean column — a TRUE job is exclusive against every participating job in its scope. */
+  readonly blocksAllColumn?: string
+  /** Tenant column — exclusion checks compare only jobs with the same tenant value. */
+  readonly tenantColumn?: string
+}
+
+export interface ResolvedExclusion {
+  readonly arrayColumn?: string
+  readonly arrayElementType: 'uuid' | 'text'
+  readonly blocksAllColumn?: string
+  readonly tenantColumn?: string
+}
+
+export function resolveExclusion(config: ExclusionConfig | undefined): ResolvedExclusion | undefined {
+  if (config === undefined) return undefined
+
+  if (config.arrayColumn === undefined && config.blocksAllColumn === undefined) {
+    throw new Error(
+      '[pipework] exclusion requires arrayColumn and/or blocksAllColumn.\n\n' +
+      '  A tenantColumn alone only scopes checks — it expresses no conflict.\n' +
+      "  Configure the conflict columns: exclusion: { arrayColumn: 'conflict_keys' }\n" +
+      "  or exclusion: { blocksAllColumn: 'exclusive' }.\n",
+    )
+  }
+
+  if (config.arrayElementType !== undefined && config.arrayColumn === undefined) {
+    throw new Error(
+      '[pipework] exclusion.arrayElementType is set but arrayColumn is not.\n\n' +
+      '  arrayElementType only describes arrayColumn.\n' +
+      '  Add arrayColumn, or remove arrayElementType.\n',
+    )
+  }
+
+  const named = [config.arrayColumn, config.blocksAllColumn, config.tenantColumn]
+    .filter((c): c is string => c !== undefined)
+  for (const column of named) {
+    assertValidIdentifier(column, 'exclusion column')
+    if (QUEUE_BASE_COLUMNS.has(column)) {
+      throw new Error(
+        `[pipework] exclusion column "${column}" collides with a base queue column.\n\n` +
+        `  The queue table already owns: ${[...QUEUE_BASE_COLUMNS].join(', ')}\n` +
+        '  Pick a different column name.\n',
+      )
+    }
+  }
+  if (new Set(named).size !== named.length) {
+    throw new Error(
+      '[pipework] exclusion columns must be distinct.\n\n' +
+      `  Got: arrayColumn=${config.arrayColumn ?? '—'}, blocksAllColumn=${config.blocksAllColumn ?? '—'}, tenantColumn=${config.tenantColumn ?? '—'}\n` +
+      '  Each role needs its own column.\n',
+    )
+  }
+
+  return {
+    ...(config.arrayColumn !== undefined ? { arrayColumn: config.arrayColumn } : {}),
+    arrayElementType: config.arrayElementType ?? 'uuid',
+    ...(config.blocksAllColumn !== undefined ? { blocksAllColumn: config.blocksAllColumn } : {}),
+    ...(config.tenantColumn !== undefined ? { tenantColumn: config.tenantColumn } : {}),
+  }
+}
+
+/**
+ * The claimability predicate for the claim query's candidate SELECT. Pure
+ * identifiers — all quoted, no values — so the result composes as a raw SQL
+ * fragment. The candidate row is aliased `candidate`, concurrent rows `r`.
+ */
+export function exclusionClaimClause(tableQ: string, exclusion: ResolvedExclusion): string {
+  const arr = exclusion.arrayColumn !== undefined ? quoteIdentifier(exclusion.arrayColumn, 'exclusion column') : undefined
+  const blocks = exclusion.blocksAllColumn !== undefined ? quoteIdentifier(exclusion.blocksAllColumn, 'exclusion column') : undefined
+  const tenant = exclusion.tenantColumn !== undefined ? quoteIdentifier(exclusion.tenantColumn, 'exclusion column') : undefined
+
+  const tenantScope = tenant !== undefined ? `r.${tenant} = candidate.${tenant} AND ` : ''
+  const noConcurrent = (condition: string): string =>
+    `NOT EXISTS (SELECT 1 FROM ${tableQ} r WHERE ${tenantScope}r.status IN ('claimed', 'running') AND ${condition})`
+
+  if (arr !== undefined && blocks !== undefined) {
+    return '(' +
+      `(candidate.${blocks} = false AND candidate.${arr} IS NULL)` +
+      ` OR (candidate.${blocks} = true AND ${noConcurrent(`(r.${arr} IS NOT NULL OR r.${blocks} = true)`)})` +
+      ` OR (candidate.${blocks} = false AND candidate.${arr} IS NOT NULL` +
+      ` AND ${noConcurrent(`r.${blocks} = true`)}` +
+      ` AND ${noConcurrent(`r.${arr} IS NOT NULL AND r.${arr} && candidate.${arr}`)})` +
+      ')'
+  }
+
+  if (arr !== undefined) {
+    return `(candidate.${arr} IS NULL OR ${noConcurrent(`r.${arr} IS NOT NULL AND r.${arr} && candidate.${arr}`)})`
+  }
+
+  // blocks-all only: participation reduces to the flag itself, so a false
+  // candidate never conflicts and a true candidate waits for true jobs.
+  return `(candidate.${blocks!} = false OR ${noConcurrent(`r.${blocks!} = true`)})`
+}

package/src/async/jobs/execute.ts

@@ -0,0 +1,219 @@
+import type { Manifold } from '../../core/pipework.js'
+import type { Handler } from '../../request/di/types.js'
+import type { TenantConfig } from '../../auth/tenant/types.js'
+import { runInContext } from '../../request/context/store.js'
+import { createJobContext } from '../../request/context/create.js'
+import { executeInTransaction } from '../../request/context/run-in-transaction.js'
+import { resolveAndExecute, resolveHandlerDatabases, buildCheckpoint } from '../../request/di/resolve.js'
+import { isTracingEnabled } from '../../trace/entry/tracing-enabled.js'
+import { openTrace } from '../../trace/entry/open-trace.js'
+import { parentTraceRef } from '../../trace/entry/parent-trace.js'
+import type { ParentTraceRef } from '../../trace/entry/open-trace.js'
+import { finalizeTrace } from '../../trace/entry/finalize-trace.js'
+import { JobAbortedError } from './errors.js'
+import { randomUUID } from 'node:crypto'
+import { serializeForTrace } from '../../trace/capture/bounded-serializer.js'
+
+/** Default timeout for setting up a tenant job's database transaction(s). */
+const DEFAULT_JOB_TRANSACTION_TIMEOUT_MS = 5000
+
+export interface ExecuteJobOptions {
+  instance: Manifold
+  jobId?: string
+  jobType?: string
+  /** 1-based attempt number, exposed as `flow.jobAttempt`. */
+  attempt?: number
+  /** The job's attempt limit, exposed as `flow.jobMaxAttempts`. */
+  maxAttempts?: number
+  auth?: unknown
+  tenant?: string | null
+  /**
+   * Tenant config carrying custom `sessionVars`. When provided alongside
+   * `tenant`, the custom session variables are propagated in addition to
+   * `pipework.tenant_id` — matching the HTTP surface's behaviour.
+   */
+  tenantConfig?: TenantConfig | null
+  input?: unknown
+  /** Timeout for multi-database transaction setup when running a tenant job. */
+  transactionTimeoutMs?: number
+  /**
+   * The trace this job continues. Omitted: the trace on the active Flow, if any.
+   * `null`: a root trace even inside a Flow. The worker surface passes the
+   * trace recorded when the job was enqueued.
+   */
+  parent?: ParentTraceRef | null
+  /** The ingress kind for the opened trace — `'cron'` for schedule-fired jobs, `'job'` otherwise. */
+  entryKind?: 'job' | 'cron'
+  /**
+   * Set when this attempt follows one that ended without failing on its own (a
+   * reap or a hand-back): the attempt's trace opens with a `pipework.job.restart`
+   * external step naming the reason and the worker that held the previous claim.
+   */
+  restart?: { readonly reason: 'reaped' | 'handed-back' | 'later'; readonly previousWorkerId: string | null }
+  /**
+   * Ends the job at the caller's deadline. On abort the job's in-flight query is
+   * cancelled server-side so its transaction rolls back and its connection
+   * returns to the pool, and `executeJob` rejects — with `signal.reason` when
+   * that is an `Error`, otherwise a `JobAbortedError` (`name: 'AbortError'`)
+   * naming the job. A handler that ignores the cancelled query keeps running;
+   * the rejection is still delivered on time.
+   */
+  signal?: AbortSignal
+}
+
+export async function executeJob<TDeps extends Record<string, unknown>, TReturn>(
+  handler: Handler<TDeps, TReturn>,
+  options: ExecuteJobOptions,
+): Promise<TReturn> {
+  const label = jobLabel(options)
+  if (options.signal?.aborted === true) throw abortReason(options.signal, label)
+
+  const jobCtxOptions: Parameters<typeof createJobContext>[0] = {
+    instance: options.instance,
+  }
+  if (options.jobId !== undefined) jobCtxOptions.jobId = options.jobId
+  if (options.jobType !== undefined) jobCtxOptions.jobType = options.jobType
+  if (options.attempt !== undefined) jobCtxOptions.attempt = options.attempt
+  if (options.maxAttempts !== undefined) jobCtxOptions.maxAttempts = options.maxAttempts
+  if (options.auth !== undefined) jobCtxOptions.auth = options.auth
+  if (options.tenant !== undefined) jobCtxOptions.tenant = options.tenant
+  if (options.tenantConfig !== undefined) jobCtxOptions.tenantConfig = options.tenantConfig
+  if (isTracingEnabled(options.instance)) {
+    jobCtxOptions.trace = openTrace({
+      instance: options.instance,
+      entryKind: options.entryKind ?? 'job',
+      parent: options.parent !== undefined ? options.parent : parentTraceRef(),
+      tenant: options.tenant ?? null,
+      auth: options.auth ?? null,
+      requestId: options.jobId ?? null,
+      sessionId: null,
+    })
+  }
+
+  if (options.restart !== undefined && jobCtxOptions.trace !== undefined && jobCtxOptions.trace !== null) {
+    const now = new Date()
+    jobCtxOptions.trace.buffer.stageExternal({
+      id: randomUUID(),
+      parentStepId: null,
+      flowStepRef: 'external:pipework.job.restart',
+      status: 'ok',
+      startedAt: now,
+      completedAt: now,
+      durationMicros: 0n,
+      capturedInputs: [serializeForTrace({ reason: options.restart.reason, previousWorkerId: options.restart.previousWorkerId })],
+      error: null,
+    })
+  }
+
+  // The handler's own signal: aborted, with the error `executeJob` rejects with,
+  // whenever the job stops being the handler's while it may still be running.
+  const own = new AbortController()
+  const ctx = createJobContext(jobCtxOptions)
+  const databases = resolveHandlerDatabases(handler, options.instance)
+  const timeoutMs = options.transactionTimeoutMs ?? DEFAULT_JOB_TRANSACTION_TIMEOUT_MS
+
+  // Manual transaction mode: the framework opens no outer transaction. The
+  // handler owns its commit boundaries through `checkpoint`, which opens a fresh
+  // tenant-scoped transaction per call (re-establishing the tenant session vars
+  // so database-side RLS sees the tenant) and commits it independently.
+  if (handler.meta.jobTransaction === 'manual') {
+    const checkpoint = buildCheckpoint(
+      handler,
+      ctx,
+      databases,
+      options.tenantConfig ?? null,
+      timeoutMs,
+      options.signal,
+      own.signal,
+    )
+    return finalizeTrace(
+      options.instance,
+      ctx.trace,
+      untilAborted(
+        runInContext(ctx, () => resolveAndExecute(handler, options.input, undefined, undefined, { checkpoint, signal: own.signal })),
+        options.signal,
+        label,
+        own,
+      ),
+    )
+  }
+
+  const run = (): Promise<TReturn> => resolveAndExecute(handler, options.input, undefined, undefined, { signal: own.signal })
+
+  // No tenant: app-level scoping does not apply, so there is nothing to
+  // propagate to Postgres — run the handler directly as before.
+  if (ctx.tenant === null || databases.length === 0) {
+    return finalizeTrace(options.instance, ctx.trace, untilAborted(runInContext(ctx, run), options.signal, label, own))
+  }
+
+  // Tenant job: wrap in a transaction and propagate session vars so
+  // database-side RLS sees the tenant — consistent with the HTTP surface.
+  return finalizeTrace(
+    options.instance,
+    ctx.trace,
+    untilAborted(
+      executeInTransaction(
+        ctx,
+        databases,
+        options.tenantConfig ?? null,
+        timeoutMs,
+        run,
+        options.signal,
+      ),
+      options.signal,
+      label,
+      own,
+    ),
+  )
+}
+
+/** `[type] id`, `[type]`, `id`, or `(anonymous)` — whatever the caller gave us to name the job by. */
+function jobLabel(options: ExecuteJobOptions): string {
+  const parts: string[] = []
+  if (options.jobType !== undefined) parts.push(`"${options.jobType}"`)
+  if (options.jobId !== undefined) parts.push(`(${options.jobId})`)
+  return parts.length === 0 ? '(anonymous)' : parts.join(' ')
+}
+
+/**
+ * The error an abort rejects with: the caller's own `Error` reason when they set
+ * one (the worker passes its timeout error this way), otherwise a
+ * `JobAbortedError` naming the job. `abort()` with no reason leaves a generic
+ * DOMException that names nothing — that is the case worth replacing.
+ */
+function abortReason(signal: AbortSignal, label: string): Error {
+  const reason: unknown = signal.reason
+  const isDefaultReason =
+    typeof DOMException === 'function' && reason instanceof DOMException && reason.name === 'AbortError'
+
+  return reason instanceof Error && !isDefaultReason
+    ? reason
+    : new JobAbortedError(label, reason)
+}
+
+/**
+ * Rejects when the signal aborts, even if the handler is still running — the
+ * caller's deadline is the caller's, not the handler's. The work promise's own
+ * rejection is swallowed once we have rejected, so a later unwind (the cancelled
+ * query surfacing) does not become an unhandled rejection. The handler's own
+ * signal aborts with that same rejection first, so it sees the abort while it runs on.
+ */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal | undefined, label: string, own: AbortController): Promise<T> {
+  if (signal === undefined) return work
+
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      work.catch(() => {})
+      const reason = abortReason(signal, label)
+      own.abort(reason)
+      reject(reason)
+    }
+    if (signal.aborted) {
+      onAbort()
+      return
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    work.then(resolve, reject).finally(() => { signal.removeEventListener('abort', onAbort) })
+  })
+}
+

package/src/async/jobs/index.ts

@@ -0,0 +1,10 @@
+export { executeJob } from './execute.js'
+export type { ExecuteJobOptions } from './execute.js'
+export { JobAbortedError, JobLaterError, JobPermanentError } from './errors.js'
+export { createQueue } from './queue.js'
+export type { Queue, QueueConfig, EnqueueOptions, EnqueueExclusion, ClaimedJob, JobClaim, JobClaimReason, ClaimedExclusion, DeadLetterInfo, ReapedJob, FailedAttempt, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig } from './queue.js'
+export type { ExclusionConfig } from './exclusion.js'
+export type { WaitOptions, WaitResult, ListenClient, ListenHandle } from './listener.js'
+export { parseCron, nextTick } from './cron.js'
+export type { CronSchedule } from './cron.js'
+export type { ScheduleSpec, ScheduleInfo, SchedulerOptions } from './scheduler.js'