pipework 0.252.0 → 0.252.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.252.1
+
+- **Fixed: published sourcemaps point at files that ship** (#894). `src/` is now in the package (and in `pipework-flow-parser` 0.1.1), so every `dist/**/*.map` source resolves; a consumer's `pipework test` no longer prints Vite's "points to missing source files" warning per pipework file, and go-to-definition through the `.d.ts` maps lands on source.
+- **Fixed: `build` starts from an empty `dist/`.** Output of deleted source files (e.g. `infra/email/sigv4`, `infra/access-links/rate-limit`) had been shipping in the package.
+
 ## 0.252.0
 
 - **Added: `observability.inFlightQueryMs`** (#892). While a statement is still running, each multiple of it logs one `query:in-flight` warning in the caller's log context (a job's id and tenant come with it): `label`, `elapsedS`, `database`, and the backend's `pid`, `state`, `waitEventType`/`waitEvent` from `pg_stat_activity`, read over a dedicated one-connection sampler (null when it is busy or slow). Nothing after the statement settles. Unset: no timer per query.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.252.0",
+  "version": "0.252.1",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",
@@ -65,6 +65,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "src",
     "bin",
     "LICENSE",
     "CHANGELOG.md",
@@ -172,7 +173,7 @@
     "pino": "^10.3.1",
     "postgres": "^3.4.9",
     "zod": "^4.4.3",
-    "pipework-flow-parser": "0.1.0"
+    "pipework-flow-parser": "0.1.1"
   },
   "peerDependencies": {
     "typescript": "^6.0.0",
@@ -189,7 +190,7 @@
     "vitest": "^4.1.5"
   },
   "scripts": {
-    "build": "pnpm --filter pipework-flow-parser build && tsc && cp src/test/globals.d.ts dist/test/globals.d.ts",
+    "build": "pnpm --filter pipework-flow-parser build && node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc && cp src/test/globals.d.ts dist/test/globals.d.ts",
     "type-check": "pnpm --filter pipework-flow-parser type-check && tsc --noEmit",
     "lint": "eslint src --max-warnings 0",
     "lint:boundaries": "node scripts/check-boundaries.js",

package/src/async/jobs/abortable-delay.ts

@@ -0,0 +1,18 @@
+/** setTimeout delay that resolves early when the signal aborts — shutdown must not wait out a backoff or poll interval. */
+export function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    if (signal?.aborted === true) {
+      resolve()
+      return
+    }
+    const onAbort = (): void => {
+      clearTimeout(timer)
+      resolve()
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}

package/src/async/jobs/claims.ts

@@ -0,0 +1,52 @@
+// The claim history a queue row keeps in its `claims` jsonb column.
+//
+// claim()'s UPDATE appends an element; every statement that ends a claim closes
+// the last one through closeClaim(), so no release path can overwrite the facts
+// of an earlier claim. Timestamps come from the database's now().
+
+import { sql } from '../../data/db/sql.js'
+import type { SQL } from '../../data/db/index.js'
+
+export type JobClaimReason = 'completed' | 'failed' | 'shutdown-returned' | 'reaped-stale' | 'later' | 'cancelled'
+
+/** One claim of a job. `releasedAt`, `reason` and `progressMark` are null while the claim is held. */
+export interface JobClaim {
+  readonly claimedAt: string
+  readonly workerId: string
+  readonly workerRelease: string | null
+  readonly releasedAt: string | null
+  readonly reason: JobClaimReason | null
+  /** The queue's `progressColumn` value at release; null when none is configured. */
+  readonly progressMark: unknown
+  /** Why a cancelled claim was cancelled; set only when `reason` is 'cancelled'. */
+  readonly cancel?: { readonly reason: string; readonly message: string }
+}
+
+/** The SET fragment that appends the claim being made. */
+export function openClaim(workerId: string, release: string | null): SQL {
+  return sql`claims = claims || jsonb_build_array(jsonb_build_object(
+          'claimedAt', now(), 'workerId', ${workerId}::text, 'workerRelease', ${release}::text,
+          'releasedAt', NULL::text, 'reason', NULL::text, 'progressMark', NULL::text))`
+}
+
+/**
+ * The SET fragment that closes the last claim, when there is one and it is
+ * still open. `progressColumn` is the quoted app column recorded as the mark.
+ * `extra` is a jsonb object SQL merged into the closed claim.
+ */
+export function closeClaim(reason: JobClaimReason | SQL, progressColumn: string | null, extra?: SQL): SQL {
+  const reasonSql = typeof reason === 'string' ? sql`${reason}::text` : reason
+  const mark = progressColumn === null ? sql`'null'::jsonb` : sql`to_jsonb(${sql.raw(progressColumn)})`
+  return sql`claims = CASE
+          WHEN jsonb_array_length(claims) > 0 AND (claims -> -1) ->> 'releasedAt' IS NULL
+          THEN jsonb_set(claims, ARRAY[(jsonb_array_length(claims) - 1)::text],
+                 (claims -> -1) || jsonb_build_object('releasedAt', now(), 'reason', ${reasonSql},
+                   'progressMark', ${mark})${extra === undefined ? sql`` : sql` || ${extra}`})
+          ELSE claims END`
+}
+
+/** Reads the column back into claims; anything but an array is no history. */
+export function parseClaims(value: unknown): readonly JobClaim[] {
+  const parsed: unknown = typeof value === 'string' ? JSON.parse(value) : value
+  return Array.isArray(parsed) ? (parsed as JobClaim[]) : []
+}

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`)})`
+}