@sixb/pg 0.0.1

package/src/run-list-query.ts

@@ -0,0 +1,108 @@
+import type { SQLClient, SqlParameter } from "./pg-client"
+
+type PgRunListTable =
+  | "agent_runs"
+  | "pipeline_runs"
+  | "pipeline_step_runs"
+  | "sync_runs"
+  | "webhook_runs"
+  | "workflow_runs"
+  | "workflow_node_runs"
+  | "workflow_agent_node_runs"
+
+/** Column projection — `sync_runs` needs the derived `checkpoint_present` flag. */
+type PgRunListSelectList = "*" | "*, checkpoint IS NOT NULL AS checkpoint_present"
+type StartedAtExpression = "started_at" | "COALESCE(started_at, created_at)"
+
+export function hasEmptyStatuses(input: { readonly statuses?: readonly unknown[] }): boolean {
+  return input.statuses !== undefined && input.statuses.length === 0
+}
+
+export function appendRunListFilters(
+  whereClauses: string[],
+  params: unknown[],
+  index: number,
+  input: {
+    readonly statuses?: readonly string[]
+    readonly startedAfter?: Date
+    readonly startedBefore?: Date
+  },
+  startedAtExpression: StartedAtExpression = "started_at"
+): number {
+  let nextIndex = index
+
+  if (input.statuses) {
+    if (input.statuses.length === 0) {
+      whereClauses.push("1 = 0")
+    } else {
+      const placeholders = input.statuses.map(() => `$${nextIndex++}`)
+      whereClauses.push(`status IN (${placeholders.join(", ")})`)
+      params.push(...input.statuses)
+    }
+  }
+
+  if (input.startedAfter) {
+    whereClauses.push(`${startedAtExpression} >= $${nextIndex++}`)
+    params.push(input.startedAfter)
+  }
+
+  if (input.startedBefore) {
+    whereClauses.push(`${startedAtExpression} <= $${nextIndex++}`)
+    params.push(input.startedBefore)
+  }
+
+  return nextIndex
+}
+
+export async function queryRunList<TRow>(input: {
+  readonly sql: SQLClient
+  readonly tableName: PgRunListTable
+  readonly whereClauses: readonly string[]
+  readonly params: readonly unknown[]
+  readonly nextIndex: number
+  readonly order?: "asc" | "desc"
+  readonly limit?: number
+  readonly offset?: number
+  readonly selectList?: PgRunListSelectList
+}): Promise<{ readonly rows: readonly TRow[]; readonly total: number; readonly hasMore: boolean }> {
+  const where = `WHERE ${input.whereClauses.join(" AND ")}`
+  const order = input.order === "asc" ? "ASC" : "DESC"
+  const offset = input.offset ?? 0
+
+  const [totalRow] = await input.sql.unsafe<{ count: string | number }[]>(
+    `SELECT COUNT(*)::bigint AS count FROM ${input.tableName} ${where}`,
+    [...input.params] as SqlParameter[]
+  )
+
+  const queryParams = [...input.params] as SqlParameter[]
+  const orderColumn =
+    input.tableName === "agent_runs"
+      ? "COALESCE(started_at, created_at)"
+      : input.tableName === "workflow_agent_node_runs"
+        ? "created_at"
+        : "started_at"
+  const idColumn = input.tableName === "workflow_agent_node_runs" ? "node_run_id" : "id"
+  let query = `
+    SELECT ${input.selectList ?? "*"} FROM ${input.tableName}
+    ${where}
+    ORDER BY ${orderColumn} ${order}, ${idColumn} ${order}
+  `
+  let nextIndex = input.nextIndex
+
+  if (input.limit !== undefined) {
+    query += ` LIMIT $${nextIndex++} OFFSET $${nextIndex++}`
+    queryParams.push(input.limit, offset)
+  } else if (offset > 0) {
+    query += ` OFFSET $${nextIndex++}`
+    queryParams.push(offset)
+  }
+
+  const rows = await input.sql.unsafe<TRow[]>(query, queryParams)
+  const total = Number(totalRow?.count ?? 0)
+
+  return {
+    rows,
+    total,
+    hasMore: offset + rows.length < total,
+  }
+}

package/src/sql.d.ts

@@ -0,0 +1,4 @@
+declare module "*.sql" {
+  const sql: string
+  export default sql
+}

package/src/storage-errors.ts

@@ -0,0 +1,72 @@
+// Map thrown errors to their PostgreSQL/porsager meaning by code rather than by matching
+// message text. Database errors arrive in the native Postgres format with a SQLSTATE on
+// `.code`; connection-layer failures arrive with porsager's own codes or, for Node socket
+// errors, as an `AggregateError` of `ECONNREFUSED`/`ETIMEDOUT`/… entries.
+
+/** PostgreSQL SQLSTATE for a unique-constraint violation. */
+const UNIQUE_VIOLATION = "23505"
+
+/**
+ * PostgreSQL SQLSTATEs in class 40 (transaction rollback) that are transient and safe to retry by
+ * replaying the whole transaction: `40001` (serialization_failure) and `40P01` (deadlock_detected).
+ * Under `SERIALIZABLE` the server raises *either* — a serialization anomaly surfaces as `40001`,
+ * while two transactions taking row locks in crossing order surface as `40P01` — and both clear on
+ * a fresh attempt. The other class-40 codes (`40002` integrity-constraint violation, `40003`
+ * statement-completion unknown) are deliberately excluded: they are not safe to blindly replay.
+ */
+const RETRYABLE_TRANSACTION_CONFLICT_CODES = new Set(["40001", "40P01"])
+
+const CONNECTION_ERROR_CODES = new Set([
+  // porsager-specific
+  "CONNECT_TIMEOUT",
+  "CONNECTION_CLOSED",
+  "CONNECTION_DESTROYED",
+  "CONNECTION_ENDED",
+  // Node socket errors
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ETIMEDOUT",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+])
+
+/** The SQLSTATE / system error code carried by a thrown database or connection error. */
+export function pgErrorCode(error: unknown): string | undefined {
+  if (error instanceof Error) {
+    const code = (error as { readonly code?: unknown }).code
+    if (typeof code === "string") {
+      return code
+    }
+  }
+  return undefined
+}
+
+/** True when the error is a PostgreSQL unique-constraint violation (SQLSTATE 23505). */
+export function isUniqueViolation(error: unknown): boolean {
+  return pgErrorCode(error) === UNIQUE_VIOLATION
+}
+
+/**
+ * True when the error is a transient transaction-rollback conflict that is safe to retry by
+ * replaying the transaction — a serialization failure (SQLSTATE 40001) or a deadlock (40P01).
+ * See {@link RETRYABLE_TRANSACTION_CONFLICT_CODES}.
+ */
+export function isRetryableTransactionConflict(error: unknown): boolean {
+  const code = pgErrorCode(error)
+  return code !== undefined && RETRYABLE_TRANSACTION_CONFLICT_CODES.has(code)
+}
+
+/**
+ * True when the error originates from the connection layer (porsager connection codes, or a
+ * Node socket failure surfaced as an `AggregateError`) rather than from a SQL statement.
+ */
+export function isConnectionError(error: unknown): boolean {
+  const code = pgErrorCode(error)
+  if (code !== undefined && CONNECTION_ERROR_CODES.has(code)) {
+    return true
+  }
+  if (error instanceof AggregateError) {
+    return error.errors.some(isConnectionError)
+  }
+  return false
+}

package/src/transactions.ts

@@ -0,0 +1,58 @@
+import { createHash } from "node:crypto"
+import type { SQL, SQLClient } from "./pg-client"
+
+export type PgStoreClient = SQL | SQLClient
+
+export interface RunPgTransactionOptions {
+  /** Open the transaction at `SERIALIZABLE`; omit for the server default (`READ COMMITTED`). */
+  readonly isolation?: "serializable"
+}
+
+export async function runPgTransaction<T>(
+  sql: PgStoreClient,
+  run: (tx: SQLClient) => Promise<T>,
+  options: RunPgTransactionOptions = {}
+): Promise<T> {
+  if (!canStartPgTransaction(sql)) {
+    return run(sql)
+  }
+
+  // porsager passes the callback a transaction-scoped client (a TransactionSql, which is an
+  // ISql == SQLClient). The `as Promise<T>` only unwraps porsager's UnwrapPromiseArray return
+  // type (our callbacks never return the pipelined-array form), not a structural cast.
+  //
+  // The isolation level is folded into `BEGIN` (`BEGIN ISOLATION LEVEL SERIALIZABLE`) rather than
+  // a separate `SET TRANSACTION` statement: one round-trip instead of two, and the level is
+  // guaranteed to take effect before any data statement of the transaction runs.
+  if (options.isolation === "serializable") {
+    return sql.begin("isolation level serializable", run) as Promise<T>
+  }
+  return sql.begin(run) as Promise<T>
+}
+
+export function authLockKey(kind: string, ...parts: readonly string[]): string {
+  return ["auth", kind, ...parts].join(":")
+}
+
+export async function lockAdvisoryKeys(sql: SQLClient, keys: readonly string[]): Promise<void> {
+  const locks = [...new Set(keys)].sort().map(advisoryLockParts)
+  if (locks.length === 0) return
+
+  await sql`
+    SELECT pg_advisory_xact_lock(locks.first_key, locks.second_key)
+    FROM unnest(
+      ${sql.array(locks.map(([first]) => first))}::integer[],
+      ${sql.array(locks.map(([, second]) => second))}::integer[]
+    ) WITH ORDINALITY AS locks(first_key, second_key, lock_order)
+    ORDER BY locks.lock_order
+  `
+}
+
+function advisoryLockParts(key: string): readonly [number, number] {
+  const hash = createHash("sha256").update(key).digest()
+  return [hash.readInt32BE(0), hash.readInt32BE(4)]
+}
+
+function canStartPgTransaction(sql: PgStoreClient): sql is SQL {
+  return typeof (sql as { readonly begin?: unknown }).begin === "function"
+}