@avelonjs/postgres 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+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,197 @@
+# @avelonjs/postgres
+
+`@avelonjs/postgres` is the Postgres database driver for Avelon. It compiles the frozen `QueryIR` into parameterized SQL, runs it through Bun's SQL client, and maps vendor failures into the framework error taxonomy. Reach for this package when your application needs transactions, deep relation loads, upserts with returning, or an independent Postgres connection beside Supabase.
+
+## Installation
+
+```sh
+bun add @avelonjs/postgres
+```
+
+Set a connection URL in the environment or pass one when constructing the driver:
+
+```sh
+export POSTGRES_URL=postgresql://postgres:avelon@127.0.0.1:5432/avelon
+```
+
+## Basic Usage
+
+```ts
+import { createPostgresDatabase } from '@avelonjs/postgres'
+import type { QueryIR } from '@avelonjs/core'
+
+const db = createPostgresDatabase({
+  url: process.env.POSTGRES_URL,
+  instance: 'primary',
+})
+
+const latest: QueryIR = {
+  table: 'posts',
+  mode: 'select',
+  select: ['id', 'title'],
+  where: [{ kind: 'null', column: 'published_at', negated: true }],
+  relations: [],
+  order: [{ column: 'published_at', direction: 'desc' }],
+  limit: 10,
+}
+
+const result = await db.execute<{ id: string; title: string }>(latest)
+```
+
+## Capabilities
+
+| Capability | Value | Notes |
+|---|---|---|
+| `transactions` | `true` | Interactive transactions through `db.transaction()` |
+| `rowSecurity` | `false` | Ward-to-RLS compilation belongs to `@avelonjs/supabase` |
+| `maxRelationDepth` | `8` | Application-side nested loads; measured against nested assay fixtures |
+| `fullTextSearch` | `false` | No portable `search()` surface in v1 |
+| `upsert` | `true` | Requires explicit conflict target and update list |
+| `returning` | `true` | Write queries may project rows |
+| `windowFunctions` | `true` | Informational; available through `raw()` |
+| `jsonOperators` | `true` | Informational; available through `raw()` |
+
+## Query Compilation
+
+The driver validates IR shape, rejects unknown public-schema identifiers, normalizes predicates, and compiles positional SQL. Empty AND is true, empty OR is false, empty IN matches nothing unless negated, and a constant-false ward or where short-circuits without a database round trip.
+
+```ts
+import { compilePostgres, combinedPredicate } from '@avelonjs/postgres'
+import type { QueryIR } from '@avelonjs/core'
+
+const query: QueryIR = {
+  table: 'assay_users',
+  mode: 'select',
+  select: ['id'],
+  where: [{ kind: 'compare', column: 'age', op: '>=', value: 18 }],
+  ward: { kind: 'compare', column: 'age', op: '<', value: 30 },
+  relations: [],
+  order: [],
+}
+
+const compiled = compilePostgres(query, combinedPredicate(query))
+// compiled.text binds age thresholds as $1 and $2
+```
+
+## Transactions
+
+```ts
+import { createPostgresDatabase } from '@avelonjs/postgres'
+
+const db = createPostgresDatabase()
+
+await db.transaction(async (tx) => {
+  await tx.execute({
+    table: 'assay_users',
+    mode: 'insert',
+    select: [],
+    where: [],
+    relations: [],
+    order: [],
+    values: { id: 'u1', email: 'one@example.test', name: 'One', age: 20, nickname: null },
+  })
+})
+```
+
+## Migrations
+
+Migrations are driver-owned SQL pairs registered on the driver instance.
+
+```ts
+import { createPostgresDatabase } from '@avelonjs/postgres'
+
+const db = createPostgresDatabase({
+  migrations: [
+    {
+      id: '20260804_create_posts',
+      up: [
+        'CREATE TABLE posts (id text PRIMARY KEY, title text NOT NULL)',
+      ],
+      down: ['DROP TABLE posts'],
+    },
+  ],
+})
+
+await db.plan()
+await db.apply()
+await db.status()
+```
+
+## Error Mapping
+
+Vendor SQLSTATE values never leave the driver. Unique violations become `Conflict`, unknown tables/columns/routines become `Invalid`, and connection failures become `Unavailable`. Every other code becomes `DriverFault`.
+
+| SQLSTATE | Framework error | Meaning |
+|---|---|---|
+| `23505` | `Conflict` | unique_violation |
+| `42P01` | `Invalid` | undefined_table |
+| `42703` | `Invalid` | undefined_column |
+| `42883` | `Invalid` | undefined_function |
+| `08006` | `Unavailable` | connection_failure |
+
+## Live Conformance
+
+Fixture provisioning is owned by this package. Reset the assay schema, then run the shared database suite against a live Postgres:
+
+```sh
+export POSTGRES_URL=postgresql://postgres:avelon@127.0.0.1:5432/avelon_test
+bun run fixtures:reset
+bun test
+```
+
+## Method Reference
+
+| Method | Signature | Description |
+|---|---|---|
+| `createPostgresDatabase` | `(options?: PostgresDatabaseOptions) => PostgresDatabase` | Constructs a driver from options or `POSTGRES_URL` / `DATABASE_URL`. |
+| `postgresDatabaseCapabilities` | `{ transactions: true, rowSecurity: false, maxRelationDepth: 8, fullTextSearch: false, upsert: true, returning: true, windowFunctions: true, jsonOperators: true }` | Exact capability declaration for the Postgres driver. |
+| `PostgresDatabaseOptions` | `interface` | Connection URL, instance name, and optional migrations. |
+| `PostgresDatabase.execute` | `(query: QueryIR) => Promise<QueryResult>` | Validates, compiles, and executes one query IR operation. |
+| `PostgresDatabase.rpc` | `(routine: string, args: Readonly<Record<string, unknown>>) => Promise<T>` | Invokes a Postgres routine; missing routines raise `Invalid`. |
+| `PostgresDatabase.transaction` | `(callback: (tx: DatabaseTransaction) => Promise<T>) => Promise<T>` | Runs the callback atomically and returns its result. |
+| `PostgresDatabase.plan` | `() => Promise<MigrationPlan>` | Returns pending migration identifiers and SQL steps. |
+| `PostgresDatabase.apply` | `() => Promise<readonly MigrationStatus[]>` | Applies pending migrations inside transactions. |
+| `PostgresDatabase.rollback` | `(steps?: number) => Promise<readonly MigrationStatus[]>` | Rolls back the newest applied migration batches. |
+| `PostgresDatabase.status` | `() => Promise<readonly MigrationStatus[]>` | Lists applied and pending migration states. |
+| `PostgresDatabase.raw` | `() => SQL` | Returns the Bun SQL client at the vendor boundary. |
+| `PostgresDatabase.resetFixtures` | `() => Promise<void>` | Recreates assay tables and `assay_echo` for live conformance. |
+| `PostgresDatabase.close` | `() => Promise<void>` | Closes the underlying SQL client pool. |
+| `compilePostgres` | `(ir: QueryIR, predicate?: Predicate) => CompiledSql` | Compiles IR to parameterized SQL without executing it. |
+| `compileSqlPredicate` | `(predicate: Predicate, bind: (value: unknown) => string) => string` | Compiles a normalized predicate to a SQL boolean expression. |
+| `CompiledSql` | `interface` | Parameterized `text` plus positional `parameters`. |
+| `normalizePredicate` | `(predicate: Predicate) => Predicate` | Applies empty-list and constant identities. |
+| `combinedPredicate` | `(ir: Pick<QueryIR, 'where' \| 'ward'>) => Predicate` | ANDs where and ward, then normalizes. |
+| `mapPostgresError` | `(error: unknown, operation: string) => never` | Maps vendor failures into framework errors. |
+| `POSTGRES_ERROR_MAP` | `readonly { sqlstate, framework, meaning }[]` | SQLSTATE values this driver maps into the taxonomy. |
+| `validateQueryIR` | `(ir: QueryIR, maxRelationDepth: number) => void` | Rejects malformed IR before compilation. |
+| `assertIdentifier` | `(value: unknown, path: string) => asserts value is string` | Rejects identifiers that are not simple SQL names. |
+| `assertQueryAgainstSchema` | `(cache: SchemaCache, query: QueryIR) => void` | Rejects unknown public-schema tables and columns. |
+| `loadSchemaCache` | `(sql: SQL) => Promise<SchemaCache>` | Loads public base tables and their columns. |
+| `SchemaCache` | `type` | `Map` of table name to column set. |
+| `planMigrations` | `(sql: SQL, migrations: readonly PostgresMigration[]) => Promise<MigrationPlan>` | Builds a pending plan from registered migrations and history. |
+| `applyMigrations` | `(sql: SQL, migrations: readonly PostgresMigration[]) => Promise<readonly MigrationStatus[]>` | Applies pending migrations inside transactions. |
+| `rollbackMigrations` | `(sql: SQL, migrations: readonly PostgresMigration[], steps?: number) => Promise<readonly MigrationStatus[]>` | Rolls back the newest applied migration batches. |
+| `statusMigrations` | `(sql: SQL, migrations: readonly PostgresMigration[]) => Promise<readonly MigrationStatus[]>` | Returns applied/pending status for every registered migration. |
+| `PostgresMigration` | `interface` | Driver-owned `id`, `up`, and `down` SQL pair. |
+| `resetAssayFixtures` | `(sql: SQL) => Promise<void>` | Provisions empty assay fixtures on a SQL client. |
+| `ASSAY_FIXTURE_SQL` | `string` | SQL that drops and recreates the database conformance fixtures. |
+
+## Testing
+
+Use the shared database conformance suite with a live database. The package ships fixture reset helpers so tests do not rely on hand-maintained schema.
+
+```ts
+import { databaseSuite } from '@avelonjs/conformance/suites'
+import { createPostgresDatabase } from '@avelonjs/postgres'
+
+databaseSuite({
+  name: 'live postgres',
+  create: async () => {
+    const driver = createPostgresDatabase()
+    await driver.resetFixtures()
+    return driver
+  },
+})
+```
+
+Unit tests cover SQL compilation and error mapping without a network round trip. Live tests require Postgres and fail closed when the database is unreachable.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@avelonjs/postgres",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Postgres database driver that compiles Avelon QueryIR to SQL.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/postgres"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "postgres",
+    "database"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "fixtures:reset": "bun ./scripts/reset-fixtures.ts"
+  },
+  "dependencies": {
+    "@avelonjs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@avelonjs/conformance": "workspace:*",
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/compile.ts

@@ -0,0 +1,177 @@
+import { Invalid, type CompareOp, type OrderTerm, type Predicate, type QueryIR } from '@avelonjs/core'
+import { combinedPredicate } from './normalize'
+import { assertIdentifier } from './validate'
+
+/** Compiled SQL text with positional parameters. */
+export interface CompiledSql {
+  /** Parameterized SQL statement. */
+  text: string
+  /** Values bound to `$1..$n` placeholders. */
+  parameters: unknown[]
+}
+
+type Row = Record<string, unknown>
+
+const SQL_OPERATOR: Record<CompareOp, string> = {
+  '=': '=',
+  '!=': '<>',
+  '<': '<',
+  '<=': '<=',
+  '>': '>',
+  '>=': '>=',
+  like: 'LIKE',
+  ilike: 'ILIKE',
+}
+
+function invalid(message: string, field: string, detail: string): never {
+  throw new Invalid(message, { metadata: { fields: { [field]: [detail] } } })
+}
+
+function quoteIdentifier(identifier: string): string {
+  assertIdentifier(identifier, 'identifier')
+  return `"${identifier}"`
+}
+
+function sqlProjection(projection: string[] | '*'): string {
+  return projection === '*' ? '*' : projection.map(quoteIdentifier).join(', ')
+}
+
+function sqlReturning(returning: string[] | '*' | undefined): string {
+  return returning === undefined ? '' : ` RETURNING ${sqlProjection(returning)}`
+}
+
+function writeRows(ir: QueryIR): { rows: Row[]; columns: string[] } {
+  const rows = (Array.isArray(ir.values) ? ir.values : [ir.values]) as Row[]
+  const columns = Object.keys(rows[0] as Row)
+  return { rows, columns }
+}
+
+function ensureUnscopedWritePredicate(predicate: Predicate, mode: 'insert' | 'upsert'): void {
+  if (predicate.kind !== 'const' || !predicate.value) {
+    invalid(
+      `${mode} with a non-constant where or ward has no documented row scope.`,
+      'where',
+      `${mode} predicates are not documented`,
+    )
+  }
+}
+
+/** Compiles a normalized predicate into a SQL boolean expression. */
+export function compileSqlPredicate(
+  predicate: Predicate,
+  bind: (value: unknown) => string,
+): string {
+  switch (predicate.kind) {
+    case 'const':
+      return predicate.value ? 'TRUE' : 'FALSE'
+    case 'compare':
+      return `${quoteIdentifier(predicate.column)} ${SQL_OPERATOR[predicate.op]} ${bind(predicate.value)}`
+    case 'null':
+      return `${quoteIdentifier(predicate.column)} IS ${predicate.negated ? 'NOT ' : ''}NULL`
+    case 'in':
+      if (predicate.values.length === 0) return predicate.negated ? 'TRUE' : 'FALSE'
+      return `${quoteIdentifier(predicate.column)} ${predicate.negated ? 'NOT ' : ''}IN (${predicate.values.map(bind).join(', ')})`
+    case 'and':
+      return `(${predicate.predicates.map((child) => compileSqlPredicate(child, bind)).join(' AND ')})`
+    case 'or':
+      return `(${predicate.predicates.map((child) => compileSqlPredicate(child, bind)).join(' OR ')})`
+    case 'not':
+      return `NOT (${compileSqlPredicate(predicate.predicate, bind)})`
+  }
+}
+
+function compileSqlOrder(order: readonly OrderTerm[]): string {
+  if (order.length === 0) return ''
+  return ` ORDER BY ${order
+    .map(
+      (term) =>
+        `${quoteIdentifier(term.column)} ${term.direction.toUpperCase()}${
+          term.nulls === undefined ? '' : ` NULLS ${term.nulls.toUpperCase()}`
+        }`,
+    )
+    .join(', ')}`
+}
+
+/**
+ * Compiles a validated query IR into parameterized Postgres SQL.
+ *
+ * Pass an already-normalized predicate when the caller has short-circuit logic of its own.
+ */
+export function compilePostgres(ir: QueryIR, predicate = combinedPredicate(ir)): CompiledSql {
+  const parameters: unknown[] = []
+  const bind = (value: unknown): string => {
+    parameters.push(value)
+    return `$${parameters.length}`
+  }
+  const where = compileSqlPredicate(predicate, bind)
+  const whereClause = where === 'TRUE' ? '' : ` WHERE ${where}`
+  const order = compileSqlOrder(ir.order)
+  const limit = ir.limit === undefined ? '' : ` LIMIT ${bind(ir.limit)}`
+  const offset = ir.offset === undefined ? '' : ` OFFSET ${bind(ir.offset)}`
+
+  switch (ir.mode) {
+    case 'select':
+      return {
+        text: `SELECT ${sqlProjection(ir.select)} FROM ${quoteIdentifier(ir.table)}${whereClause}${order}${limit}${offset}`,
+        parameters,
+      }
+    case 'count':
+      return {
+        text: `SELECT COUNT(*)::int AS count FROM ${quoteIdentifier(ir.table)}${whereClause}`,
+        parameters,
+      }
+    case 'insert': {
+      ensureUnscopedWritePredicate(predicate, 'insert')
+      const { rows, columns } = writeRows(ir)
+      const values = rows
+        .map((row) => `(${columns.map((column) => bind(row[column])).join(', ')})`)
+        .join(', ')
+      return {
+        text: `INSERT INTO ${quoteIdentifier(ir.table)} (${columns.map(quoteIdentifier).join(', ')}) VALUES ${values}${sqlReturning(ir.returning)}`,
+        parameters,
+      }
+    }
+    case 'update': {
+      const row = writeRows(ir).rows[0] as Row
+      const assignments = Object.keys(row).map(
+        (column) => `${quoteIdentifier(column)} = ${bind(row[column])}`,
+      )
+      return {
+        text: `UPDATE ${quoteIdentifier(ir.table)} SET ${assignments.join(', ')}${whereClause}${sqlReturning(ir.returning)}`,
+        parameters,
+      }
+    }
+    case 'delete':
+      return {
+        text: `DELETE FROM ${quoteIdentifier(ir.table)}${whereClause}${sqlReturning(ir.returning)}`,
+        parameters,
+      }
+    case 'upsert': {
+      ensureUnscopedWritePredicate(predicate, 'upsert')
+      const conflict = ir.conflict
+      if (conflict === undefined) invalid('upsert requires conflict.', 'conflict', 'Required for upsert')
+      const { rows, columns } = writeRows(ir)
+      const values = rows
+        .map((row) => `(${columns.map((column) => bind(row[column])).join(', ')})`)
+        .join(', ')
+      const updateColumns =
+        conflict.update === '*'
+          ? columns.filter((column) => !conflict.columns.includes(column))
+          : [...conflict.update]
+      if (updateColumns.length === 0) {
+        invalid(
+          'upsert update list resolved to no columns.',
+          'conflict',
+          'Provide at least one update column',
+        )
+      }
+      const assignments = updateColumns.map(
+        (column) => `${quoteIdentifier(column)} = EXCLUDED.${quoteIdentifier(column)}`,
+      )
+      return {
+        text: `INSERT INTO ${quoteIdentifier(ir.table)} (${columns.map(quoteIdentifier).join(', ')}) VALUES ${values} ON CONFLICT (${conflict.columns.map(quoteIdentifier).join(', ')}) DO UPDATE SET ${assignments.join(', ')}${sqlReturning(ir.returning)}`,
+        parameters,
+      }
+    }
+  }
+}