@avelonjs/postgres 0.1.0

package/src/driver.ts

@@ -0,0 +1,386 @@
+import { SQL } from 'bun'
+import {
+  Invalid,
+  type DatabaseDriver,
+  type DatabaseTransaction,
+  type MigrationPlan,
+  type MigrationStatus,
+  type Predicate,
+  type QueryIR,
+  type QueryResult,
+  type RelationLoad,
+  type TransactionSurface,
+} from '@avelonjs/core'
+import { compilePostgres } from './compile'
+import { mapPostgresError } from './errors'
+import { resetAssayFixtures } from './fixtures'
+import {
+  applyMigrations,
+  planMigrations,
+  rollbackMigrations,
+  statusMigrations,
+  type PostgresMigration,
+} from './migrations'
+import { combinedPredicate } from './normalize'
+import { assertQueryAgainstSchema, loadSchemaCache, type SchemaCache } from './schema'
+import { validateQueryIR } from './validate'
+
+/** Exact capability declaration for the Postgres database driver. */
+export const postgresDatabaseCapabilities = {
+  transactions: true,
+  rowSecurity: false,
+  /** Measured via nested application-side relation loads; not a PostgREST embed limit. */
+  maxRelationDepth: 8,
+  fullTextSearch: false,
+  upsert: true,
+  returning: true,
+  windowFunctions: true,
+  jsonOperators: true,
+} as const
+
+/** Construction options for {@link PostgresDatabase}. */
+export interface PostgresDatabaseOptions {
+  /** Postgres connection URL. Defaults to `POSTGRES_URL` or `DATABASE_URL`. */
+  url?: string
+  /** Configured connection name reported on the driver. */
+  instance?: string
+  /** Optional driver-owned migrations registered with this instance. */
+  migrations?: readonly PostgresMigration[]
+}
+
+type Row = Record<string, unknown>
+type SqlClient = SQL
+
+function defaultUrl(): string {
+  return (
+    process.env.POSTGRES_URL ??
+    process.env.DATABASE_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_test'
+  )
+}
+
+function includeColumns(select: string[] | '*', columns: string[]): string[] | '*' {
+  if (select === '*') return '*'
+  return [...new Set([...select, ...columns])]
+}
+
+function projectRow(row: Row, select: string[] | '*', relations: readonly RelationLoad[]): Row {
+  const output: Row = {}
+  const columns =
+    select === '*'
+      ? Object.keys(row).filter((column) => !relations.some((relation) => relation.relation === column))
+      : select
+  for (const column of columns) output[column] = row[column]
+  for (const relation of relations) output[relation.relation] = row[relation.relation]
+  return output
+}
+
+function unique(values: unknown[]): unknown[] {
+  const output: unknown[] = []
+  for (const value of values) {
+    if (!output.some((existing) => sqlEqual(existing, value))) output.push(value)
+  }
+  return output
+}
+
+function sqlEqual(left: unknown, right: unknown): boolean {
+  if (left === null || left === undefined || right === null || right === undefined) return false
+  return left === right
+}
+
+function asRows(result: unknown): Row[] {
+  if (!Array.isArray(result)) return []
+  return result.map((row) => ({ ...(row as Row) }))
+}
+
+function resultCount(result: unknown): number {
+  if (!Array.isArray(result)) return 0
+  const count = Reflect.get(result, 'count')
+  return typeof count === 'number' ? count : result.length
+}
+
+/**
+ * Postgres implementation of the frozen database contract.
+ *
+ * Vendor access stays inside this package through Bun's SQL client. Application code reaches the
+ * driver only through the database facade and never imports `bun` SQL APIs.
+ */
+export class PostgresDatabase
+  implements
+    DatabaseDriver<typeof postgresDatabaseCapabilities, SQL>,
+    TransactionSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'postgres'
+
+  /** Configured connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities: typeof postgresDatabaseCapabilities
+
+  readonly #sql: SQL
+  readonly #migrations: readonly PostgresMigration[]
+  #schema: SchemaCache | undefined
+  #roundTrips = 0
+
+  /** Creates a driver bound to one Postgres connection URL. */
+  constructor(options: PostgresDatabaseOptions = {}) {
+    this.instance = options.instance ?? 'default'
+    this.#migrations = options.migrations ?? []
+    this.capabilities = postgresDatabaseCapabilities
+    this.#sql = new SQL(options.url ?? defaultUrl())
+  }
+
+  /** Number of statements that reached Postgres. Used by conformance short-circuit checks. */
+  get roundTrips(): number {
+    return this.#roundTrips
+  }
+
+  /** Returns the underlying Bun SQL client. */
+  raw(): SQL {
+    return this.#sql
+  }
+
+  /** Drops and recreates the assay fixture schema used by live conformance. */
+  async resetFixtures(): Promise<void> {
+    await resetAssayFixtures(this.#sql)
+    this.#schema = undefined
+  }
+
+  /** Closes the underlying SQL client pool. */
+  async close(): Promise<void> {
+    await this.#sql.close()
+  }
+
+  /** Compiles and executes one query IR operation. */
+  async execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>> {
+    return this.#execute(this.#sql, query) as Promise<QueryResult<TRow>>
+  }
+
+  /** Invokes a named Postgres routine. Missing routines map to `Invalid`. */
+  async rpc<TResult = unknown>(
+    routine: string,
+    args: Readonly<Record<string, unknown>>,
+  ): Promise<TResult> {
+    try {
+      this.#roundTrips += 1
+      const rows = asRows(
+        await this.#sql.unsafe(`SELECT ${quoteRoutine(routine)}($1::jsonb) AS result`, [
+          JSON.stringify(args),
+        ]),
+      )
+      return decodeJsonResult(rows[0]?.result) as TResult
+    } catch (error) {
+      mapPostgresError(error, 'rpc')
+    }
+  }
+
+  /** Produces the pending migration plan. */
+  async plan(): Promise<MigrationPlan> {
+    return planMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Applies pending migrations. */
+  async apply(): Promise<readonly MigrationStatus[]> {
+    return applyMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Rolls back applied migration batches. */
+  async rollback(steps?: number): Promise<readonly MigrationStatus[]> {
+    return rollbackMigrations(this.#sql, this.#migrations, steps)
+  }
+
+  /** Returns all migration states. */
+  async status(): Promise<readonly MigrationStatus[]> {
+    return statusMigrations(this.#sql, this.#migrations)
+  }
+
+  /** Runs a callback inside a Postgres transaction. */
+  async transaction<TResult>(
+    callback: (transaction: DatabaseTransaction) => Promise<TResult>,
+  ): Promise<TResult> {
+    try {
+      return await this.#sql.begin(async (tx) => {
+        const transaction: DatabaseTransaction = {
+          execute: <TRow = Record<string, unknown>>(query: QueryIR) =>
+            this.#execute(tx as SqlClient, query) as Promise<QueryResult<TRow>>,
+          rpc: async <TResultRpc = unknown>(
+            routine: string,
+            args: Readonly<Record<string, unknown>>,
+          ) => {
+            try {
+              this.#roundTrips += 1
+              const rows = asRows(
+                await (tx as SqlClient).unsafe(`SELECT ${quoteRoutine(routine)}($1::jsonb) AS result`, [
+                  JSON.stringify(args),
+                ]),
+              )
+              return decodeJsonResult(rows[0]?.result) as TResultRpc
+            } catch (error) {
+              mapPostgresError(error, 'rpc')
+            }
+          },
+        }
+        return callback(transaction)
+      })
+    } catch (error) {
+      if (
+        error instanceof Invalid ||
+        (error instanceof Error &&
+          (error.name === 'Conflict' ||
+            error.name === 'DriverFault' ||
+            error.name === 'Unavailable'))
+      ) {
+        throw error
+      }
+      mapPostgresError(error, 'transaction')
+    }
+  }
+
+  async #schemaCache(): Promise<SchemaCache> {
+    if (this.#schema === undefined) this.#schema = await loadSchemaCache(this.#sql)
+    return this.#schema
+  }
+
+  async #execute(sql: SqlClient, ir: QueryIR): Promise<QueryResult> {
+    validateQueryIR(ir, this.capabilities.maxRelationDepth)
+    assertQueryAgainstSchema(await this.#schemaCache(), ir)
+    const predicate = combinedPredicate(ir)
+
+    if (predicate.kind === 'const' && !predicate.value) {
+      return ir.mode === 'count' ? { rows: [], affected: 0, count: 0 } : { rows: [], affected: 0 }
+    }
+
+    if ((ir.mode === 'insert' || ir.mode === 'upsert') && predicate.kind !== 'const') {
+      throw new Invalid(`${ir.mode} with a non-constant where or ward has no documented row scope.`, {
+        metadata: { fields: { where: [`${ir.mode} predicates are not documented`] } },
+      })
+    }
+
+    if (ir.mode === 'select') {
+      const primitive: QueryIR = {
+        ...ir,
+        select: includeColumns(
+          ir.select,
+          ir.relations.map((relation) => relation.localKey),
+        ),
+        relations: [],
+      }
+      const rows = await this.#executePrimitive(sql, primitive, predicate)
+      await this.#loadRelations(sql, rows, ir.relations)
+      return {
+        rows: rows.map((row) => projectRow(row, ir.select, ir.relations)),
+        affected: 0,
+      }
+    }
+
+    if (ir.mode === 'count') {
+      const rows = await this.#executePrimitive(sql, ir, predicate)
+      const count = Number(rows[0]?.count ?? 0)
+      return { rows: [], affected: 0, count }
+    }
+
+    const rows = await this.#executePrimitive(sql, ir, predicate)
+    const affected = resultCount(rows)
+    return {
+      rows: ir.returning === undefined ? [] : rows,
+      affected,
+    }
+  }
+
+  async #executePrimitive(sql: SqlClient, ir: QueryIR, predicate: Predicate): Promise<Row[]> {
+    const compiled = compilePostgres(ir, predicate)
+    try {
+      this.#roundTrips += 1
+      const result = await sql.unsafe(compiled.text, compiled.parameters)
+      const rows = asRows(result)
+      // Preserve Bun's statement count for writes without RETURNING (empty row arrays).
+      Object.defineProperty(rows, 'count', {
+        value: resultCount(result),
+        enumerable: false,
+      })
+      return rows
+    } catch (error) {
+      mapPostgresError(error, 'execute')
+    }
+  }
+
+  async #loadRelations(
+    sql: SqlClient,
+    parents: Row[],
+    relations: readonly RelationLoad[],
+  ): Promise<void> {
+    for (const relation of relations) {
+      const keys = unique(
+        parents
+          .map((parent) => parent[relation.localKey])
+          .filter((value) => value !== null && value !== undefined),
+      )
+
+      if (keys.length === 0) {
+        for (const parent of parents) {
+          parent[relation.relation] = relation.kind === 'hasMany' ? [] : null
+        }
+        continue
+      }
+
+      const childSelect = includeColumns(relation.select, [
+        relation.foreignKey,
+        ...relation.relations.map((nested) => nested.localKey),
+      ])
+      const childWhere: Predicate[] = [
+        ...(relation.where === null ? [] : [relation.where]),
+        { kind: 'in', column: relation.foreignKey, values: keys, negated: false },
+      ]
+      const childIR: QueryIR = {
+        table: relation.table,
+        mode: 'select',
+        select: childSelect,
+        where: childWhere,
+        relations: [],
+        order: relation.order,
+      }
+      const predicate = combinedPredicate(childIR)
+      const children =
+        predicate.kind === 'const' && !predicate.value
+          ? []
+          : await this.#executePrimitive(sql, childIR, predicate)
+      await this.#loadRelations(sql, children, relation.relations)
+
+      for (const parent of parents) {
+        const matches = children.filter((child) =>
+          sqlEqual(child[relation.foreignKey], parent[relation.localKey]),
+        )
+        const limited = relation.limit === undefined ? matches : matches.slice(0, relation.limit)
+        const projected = limited.map((child) =>
+          projectRow(child, relation.select, relation.relations),
+        )
+        parent[relation.relation] = relation.kind === 'hasMany' ? projected : (projected[0] ?? null)
+      }
+    }
+  }
+}
+
+function quoteRoutine(routine: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(routine)) {
+    throw new Invalid('Routine name must be a simple identifier.', {
+      metadata: { fields: { routine: [routine] } },
+    })
+  }
+  return `"${routine}"`
+}
+
+function decodeJsonResult(value: unknown): unknown {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+/** Creates a Postgres database driver from options or environment defaults. */
+export function createPostgresDatabase(options: PostgresDatabaseOptions = {}): PostgresDatabase {
+  return new PostgresDatabase(options)
+}

package/src/errors.ts

@@ -0,0 +1,100 @@
+import { Conflict, DriverFault, Invalid, Unavailable } from '@avelonjs/core'
+
+interface PostgresErrorLike {
+  readonly name?: string
+  readonly message?: string
+  readonly errno?: string | number
+  readonly code?: string
+  readonly detail?: string
+  readonly table?: string
+  readonly constraint?: string
+  readonly routine?: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function asPostgresError(error: unknown): PostgresErrorLike | undefined {
+  if (!isRecord(error)) return undefined
+  return error as PostgresErrorLike
+}
+
+function sqlState(error: PostgresErrorLike): string | undefined {
+  if (typeof error.errno === 'string') return error.errno
+  if (typeof error.errno === 'number') return String(error.errno)
+  return undefined
+}
+
+/**
+ * Maps a Bun/Postgres vendor failure into the framework error taxonomy.
+ *
+ * Unknown codes become `DriverFault` rather than leaking vendor shapes into application code.
+ */
+export function mapPostgresError(error: unknown, operation: string): never {
+  const pg = asPostgresError(error)
+  const state = pg === undefined ? undefined : sqlState(pg)
+  const message = pg?.message ?? (error instanceof Error ? error.message : 'Postgres driver failure')
+
+  if (state === '23505') {
+    throw new Conflict(message, {
+      metadata: {
+        resource: pg?.table,
+        key: pg?.constraint,
+      },
+      cause: error,
+    })
+  }
+
+  if (state === '42P01' || state === '42703') {
+    throw new Invalid(message, {
+      metadata: {
+        fields: {
+          [state === '42P01' ? 'table' : 'select']: [message],
+        },
+      },
+      cause: error,
+    })
+  }
+
+  if (state === '42883') {
+    const routine = extractRoutineName(message) ?? 'unknown'
+    throw new Invalid(message, {
+      metadata: { fields: { routine: [routine] } },
+      cause: error,
+    })
+  }
+
+  if (state === '57P01' || state === '57P03' || state === '08006' || state === '08001') {
+    throw new Unavailable(message, {
+      metadata: { service: 'postgres' },
+      cause: error,
+    })
+  }
+
+  throw new DriverFault(message, {
+    metadata: { driver: 'database', operation },
+    cause: error,
+  })
+}
+
+function extractRoutineName(message: string): string | undefined {
+  const match = /function ([a-zA-Z0-9_.]+)\(/.exec(message)
+  return match?.[1]
+}
+
+/**
+ * Vendor SQLSTATE codes this driver maps, with the framework class they become.
+ *
+ * Kept as a table so live error-mapping tests and docs stay aligned.
+ */
+export const POSTGRES_ERROR_MAP = [
+  { sqlstate: '23505', framework: 'Conflict', meaning: 'unique_violation' },
+  { sqlstate: '42P01', framework: 'Invalid', meaning: 'undefined_table' },
+  { sqlstate: '42703', framework: 'Invalid', meaning: 'undefined_column' },
+  { sqlstate: '42883', framework: 'Invalid', meaning: 'undefined_function' },
+  { sqlstate: '57P01', framework: 'Unavailable', meaning: 'admin_shutdown' },
+  { sqlstate: '57P03', framework: 'Unavailable', meaning: 'cannot_connect_now' },
+  { sqlstate: '08006', framework: 'Unavailable', meaning: 'connection_failure' },
+  { sqlstate: '08001', framework: 'Unavailable', meaning: 'sqlclient_unable_to_establish_sqlconnection' },
+] as const

package/src/fixtures.ts

@@ -0,0 +1,59 @@
+import type { SQL } from 'bun'
+
+/** SQL that drops and recreates the database conformance fixtures. */
+export const ASSAY_FIXTURE_SQL = `
+DROP TABLE IF EXISTS assay_reactions CASCADE;
+DROP TABLE IF EXISTS assay_comments CASCADE;
+DROP TABLE IF EXISTS assay_posts CASCADE;
+DROP TABLE IF EXISTS assay_profiles CASCADE;
+DROP TABLE IF EXISTS assay_users CASCADE;
+DROP FUNCTION IF EXISTS assay_echo(jsonb);
+
+CREATE TABLE assay_users (
+  id text PRIMARY KEY,
+  email text NOT NULL UNIQUE,
+  name text NOT NULL,
+  age integer NOT NULL,
+  nickname text
+);
+
+CREATE TABLE assay_profiles (
+  id text PRIMARY KEY,
+  user_id text NOT NULL UNIQUE REFERENCES assay_users(id) ON DELETE CASCADE,
+  bio text NOT NULL
+);
+
+CREATE TABLE assay_posts (
+  id text PRIMARY KEY,
+  user_id text NOT NULL REFERENCES assay_users(id) ON DELETE CASCADE,
+  title text NOT NULL,
+  score integer NOT NULL,
+  published_at timestamptz
+);
+
+CREATE TABLE assay_comments (
+  id text PRIMARY KEY,
+  post_id text NOT NULL REFERENCES assay_posts(id) ON DELETE CASCADE,
+  body text NOT NULL,
+  position integer NOT NULL
+);
+
+CREATE TABLE assay_reactions (
+  id text PRIMARY KEY,
+  comment_id text NOT NULL REFERENCES assay_comments(id) ON DELETE CASCADE,
+  kind text NOT NULL
+);
+
+CREATE OR REPLACE FUNCTION assay_echo(args jsonb)
+RETURNS jsonb
+LANGUAGE sql
+IMMUTABLE
+AS $$
+  SELECT args;
+$$;
+`
+
+/** Provisions empty assay fixture tables and the `assay_echo` routine. */
+export async function resetAssayFixtures(sql: SQL): Promise<void> {
+  await sql.unsafe(ASSAY_FIXTURE_SQL)
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { compilePostgres, compileSqlPredicate, type CompiledSql } from './compile'
+export {
+  createPostgresDatabase,
+  PostgresDatabase,
+  postgresDatabaseCapabilities,
+  type PostgresDatabaseOptions,
+} from './driver'
+export { mapPostgresError, POSTGRES_ERROR_MAP } from './errors'
+export { ASSAY_FIXTURE_SQL, resetAssayFixtures } from './fixtures'
+export {
+  applyMigrations,
+  planMigrations,
+  rollbackMigrations,
+  statusMigrations,
+  type PostgresMigration,
+} from './migrations'
+export { combinedPredicate, normalizePredicate } from './normalize'
+export { assertQueryAgainstSchema, loadSchemaCache, type SchemaCache } from './schema'
+export { assertIdentifier, validateQueryIR } from './validate'

package/src/migrations.ts

@@ -0,0 +1,123 @@
+import type { SQL } from 'bun'
+import type { MigrationPlan, MigrationStatus } from '@avelonjs/core'
+import { mapPostgresError } from './errors'
+
+/** One driver-owned SQL migration pair. */
+export interface PostgresMigration {
+  /** Stable migration identifier. */
+  id: string
+  /** Statements applied in order. */
+  up: readonly string[]
+  /** Statements used to roll the migration back. */
+  down: readonly string[]
+}
+
+const HISTORY_TABLE = 'avelon_migrations'
+
+async function ensureHistory(sql: SQL): Promise<void> {
+  try {
+    await sql.unsafe(`
+      CREATE TABLE IF NOT EXISTS ${HISTORY_TABLE} (
+        id text PRIMARY KEY,
+        applied_at timestamptz NOT NULL DEFAULT now()
+      )
+    `)
+  } catch (error) {
+    mapPostgresError(error, 'migrations.ensureHistory')
+  }
+}
+
+async function appliedIds(sql: SQL): Promise<Set<string>> {
+  await ensureHistory(sql)
+  try {
+    const rows = (await sql.unsafe(`SELECT id FROM ${HISTORY_TABLE}`)) as Array<{ id: string }>
+    return new Set(rows.map((row) => row.id))
+  } catch (error) {
+    mapPostgresError(error, 'migrations.status')
+  }
+}
+
+/** Builds a pending migration plan from registered migrations and history. */
+export async function planMigrations(
+  sql: SQL,
+  migrations: readonly PostgresMigration[],
+): Promise<MigrationPlan> {
+  const applied = await appliedIds(sql)
+  const pending = migrations.filter((migration) => !applied.has(migration.id))
+  return {
+    id: `postgres-${pending.map((migration) => migration.id).join('+') || 'empty'}`,
+    migrations: pending.map((migration) => migration.id),
+    steps: pending.flatMap((migration) => migration.up),
+  }
+}
+
+/** Applies every pending migration and returns the resulting statuses. */
+export async function applyMigrations(
+  sql: SQL,
+  migrations: readonly PostgresMigration[],
+): Promise<readonly MigrationStatus[]> {
+  const plan = await planMigrations(sql, migrations)
+  for (const id of plan.migrations) {
+    const migration = migrations.find((entry) => entry.id === id)
+    if (migration === undefined) continue
+    try {
+      await sql.begin(async (tx) => {
+        for (const statement of migration.up) await tx.unsafe(statement)
+        await tx.unsafe(`INSERT INTO ${HISTORY_TABLE} (id) VALUES ($1)`, [id])
+      })
+    } catch (error) {
+      mapPostgresError(error, 'migrations.apply')
+    }
+  }
+  return statusMigrations(sql, migrations)
+}
+
+/** Rolls back the newest applied migration batches. */
+export async function rollbackMigrations(
+  sql: SQL,
+  migrations: readonly PostgresMigration[],
+  steps = 1,
+): Promise<readonly MigrationStatus[]> {
+  await ensureHistory(sql)
+  const count = Number.isInteger(steps) && steps > 0 ? steps : 1
+  try {
+    const applied = (await sql.unsafe(
+      `SELECT id, applied_at FROM ${HISTORY_TABLE} ORDER BY applied_at DESC LIMIT $1`,
+      [count],
+    )) as Array<{ id: string; applied_at: Date }>
+
+    for (const row of applied) {
+      const migration = migrations.find((entry) => entry.id === row.id)
+      if (migration === undefined) continue
+      await sql.begin(async (tx) => {
+        for (const statement of migration.down) await tx.unsafe(statement)
+        await tx.unsafe(`DELETE FROM ${HISTORY_TABLE} WHERE id = $1`, [row.id])
+      })
+    }
+  } catch (error) {
+    mapPostgresError(error, 'migrations.rollback')
+  }
+  return statusMigrations(sql, migrations)
+}
+
+/** Returns applied/pending status for every registered migration. */
+export async function statusMigrations(
+  sql: SQL,
+  migrations: readonly PostgresMigration[],
+): Promise<readonly MigrationStatus[]> {
+  await ensureHistory(sql)
+  try {
+    const rows = (await sql.unsafe(
+      `SELECT id, applied_at FROM ${HISTORY_TABLE}`,
+    )) as Array<{ id: string; applied_at: Date }>
+    const byId = new Map(rows.map((row) => [row.id, row.applied_at]))
+    return migrations.map((migration) => {
+      const appliedAt = byId.get(migration.id)
+      return appliedAt === undefined
+        ? { id: migration.id, applied: false }
+        : { id: migration.id, applied: true, appliedAt }
+    })
+  } catch (error) {
+    mapPostgresError(error, 'migrations.status')
+  }
+}