@avelonjs/neon 0.3.0

package/src/database/driver.ts

@@ -0,0 +1,263 @@
+import { neon, Pool, type PoolClient } from '@neondatabase/serverless'
+import {
+  Invalid,
+  type DatabaseDriver,
+  type DatabaseTransaction,
+  type MigrationPlan,
+  type MigrationStatus,
+  type QueryIR,
+  type QueryResult,
+  type TransactionSurface,
+} from '@avelonjs/core'
+import {
+  applyMigrations,
+  ASSAY_FIXTURE_STATEMENTS,
+  executeQueryIR,
+  executeRpc,
+  loadSchemaCache,
+  mapPostgresError,
+  planMigrations,
+  rollbackMigrations,
+  statusMigrations,
+  type PostgresMigration,
+  type SchemaCache,
+  type SqlBatchRunner,
+  type SqlRows,
+  type SqlRunner,
+} from '@avelonjs/postgres/sql'
+
+/** Exact capability declaration for the Neon database driver. */
+export const neonDatabaseCapabilities = {
+  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 NeonDatabase}. */
+export interface NeonDatabaseOptions {
+  /** Neon or Postgres connection URL. Defaults to `NEON_DATABASE_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[]
+}
+
+/** Vendor client returned by {@link NeonDatabase.raw}. */
+export type NeonSql = ReturnType<typeof neon>
+
+interface VendorRows {
+  readonly rows: readonly Record<string, unknown>[]
+  readonly rowCount: number | null
+}
+
+function defaultUrl(): string {
+  return (
+    process.env.NEON_DATABASE_URL ??
+    process.env.DATABASE_URL ??
+    process.env.POSTGRES_URL ??
+    'postgresql://postgres:avelon@127.0.0.1:5432/avelon_test'
+  )
+}
+
+function toSqlRows(result: VendorRows): SqlRows {
+  return {
+    rows: result.rows.map((row) => ({ ...row })),
+    count: result.rowCount ?? result.rows.length,
+  }
+}
+
+/**
+ * Neon database driver.
+ *
+ * Query IR compilation, migrations, and schema checks come from `@avelonjs/postgres/sql`, which
+ * carries no `bun` specifier anywhere in its import graph, so this driver runs on Node. Reads,
+ * writes, RPC, and migrations go over Neon's HTTP endpoint. `transaction()` needs an interactive
+ * session, which HTTP cannot give, so it opens a WebSocket `Pool` connection on first use.
+ */
+export class NeonDatabase
+  implements DatabaseDriver<typeof neonDatabaseCapabilities, NeonSql>, TransactionSurface
+{
+  /** Driver implementation name. */
+  readonly name = 'neon'
+
+  /** Configured connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = neonDatabaseCapabilities
+
+  readonly #url: string
+  readonly #sql: NeonSql
+  readonly #runner: SqlBatchRunner
+  readonly #migrations: readonly PostgresMigration[]
+  #pool: Pool | undefined
+  #schema: SchemaCache | undefined
+  #roundTrips = 0
+
+  /** Creates a driver bound to one Neon connection URL. */
+  constructor(options: NeonDatabaseOptions = {}) {
+    this.#url = options.url ?? defaultUrl()
+    this.instance = options.instance ?? 'default'
+    this.#migrations = options.migrations ?? []
+    this.#sql = neon(this.#url)
+    this.#runner = {
+      unsafe: async (text, parameters) =>
+        toSqlRows(
+          await this.#sql.query<false, true>(
+            text,
+            parameters === undefined ? [] : [...parameters],
+            {
+              fullResults: true,
+            },
+          ),
+        ),
+      batch: async (statements) => {
+        await this.#sql.transaction(
+          statements.map((statement) => this.#sql.query(statement.text, [...statement.parameters])),
+        )
+      },
+    }
+  }
+
+  /** Number of statements that reached Postgres. Used by conformance short-circuit checks. */
+  get roundTrips(): number {
+    return this.#roundTrips
+  }
+
+  /** Returns the `@neondatabase/serverless` query function. */
+  raw(): NeonSql {
+    return this.#sql
+  }
+
+  /** Drops and recreates the assay fixture schema used by live conformance. */
+  async resetFixtures(): Promise<void> {
+    for (const statement of ASSAY_FIXTURE_STATEMENTS) await this.#runner.unsafe(statement)
+    this.#schema = undefined
+  }
+
+  /** Closes the WebSocket pool when `transaction()` opened one. HTTP queries hold nothing. */
+  async close(): Promise<void> {
+    const pool = this.#pool
+    this.#pool = undefined
+    if (pool !== undefined) await pool.end()
+  }
+
+  /** Compiles and executes one query IR operation. */
+  async execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>> {
+    return this.#execute(this.#runner, 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> {
+    return executeRpc(this.#runner, routine, args, this.#countRoundTrip) as Promise<TResult>
+  }
+
+  /** Produces the pending migration plan. */
+  async plan(): Promise<MigrationPlan> {
+    return planMigrations(this.#runner, this.#migrations)
+  }
+
+  /** Applies pending migrations. */
+  async apply(): Promise<readonly MigrationStatus[]> {
+    return applyMigrations(this.#runner, this.#migrations)
+  }
+
+  /** Rolls back applied migration batches. */
+  async rollback(steps?: number): Promise<readonly MigrationStatus[]> {
+    return rollbackMigrations(this.#runner, this.#migrations, steps)
+  }
+
+  /** Returns all migration states. */
+  async status(): Promise<readonly MigrationStatus[]> {
+    return statusMigrations(this.#runner, this.#migrations)
+  }
+
+  /**
+   * Runs a callback inside a Postgres transaction.
+   *
+   * The callback reads rows before deciding what to issue next, so this takes a session-backed
+   * WebSocket connection rather than Neon's HTTP endpoint, whose transactions are non-interactive.
+   */
+  async transaction<TResult>(
+    callback: (transaction: DatabaseTransaction) => Promise<TResult>,
+  ): Promise<TResult> {
+    const client = await this.#connect()
+    const runner: SqlRunner = {
+      unsafe: async (text, parameters) =>
+        toSqlRows(await client.query(text, parameters === undefined ? [] : [...parameters])),
+    }
+    try {
+      await client.query('BEGIN')
+      const result = await callback({
+        execute: <TRow = Record<string, unknown>>(query: QueryIR) =>
+          this.#execute(runner, query) as Promise<QueryResult<TRow>>,
+        rpc: <TResultRpc = unknown>(routine: string, args: Readonly<Record<string, unknown>>) =>
+          executeRpc(runner, routine, args, this.#countRoundTrip) as Promise<TResultRpc>,
+      })
+      await client.query('COMMIT')
+      return result
+    } catch (error) {
+      await client.query('ROLLBACK').catch(() => undefined)
+      if (
+        error instanceof Invalid ||
+        (error instanceof Error &&
+          (error.name === 'Conflict' ||
+            error.name === 'DriverFault' ||
+            error.name === 'Unavailable'))
+      ) {
+        throw error
+      }
+      mapPostgresError(error, 'transaction')
+    } finally {
+      client.release()
+    }
+  }
+
+  readonly #countRoundTrip = (): void => {
+    this.#roundTrips += 1
+  }
+
+  async #connect(): Promise<PoolClient> {
+    if (this.#pool === undefined) {
+      const pool = new Pool({ connectionString: this.#url })
+      // An idle pooled connection dropped by the server emits 'error'; unhandled, that ends the process.
+      pool.on('error', () => undefined)
+      this.#pool = pool
+    }
+    try {
+      return await this.#pool.connect()
+    } catch (error) {
+      mapPostgresError(error, 'transaction')
+    }
+  }
+
+  async #schemaCache(): Promise<SchemaCache> {
+    this.#schema ??= await loadSchemaCache(this.#runner)
+    return this.#schema
+  }
+
+  async #execute(runner: SqlRunner, ir: QueryIR): Promise<QueryResult> {
+    return executeQueryIR(
+      runner,
+      await this.#schemaCache(),
+      ir,
+      this.capabilities.maxRelationDepth,
+      this.#countRoundTrip,
+    )
+  }
+}
+
+/** Creates a Neon database driver from options or environment defaults. */
+export function createNeonDatabase(options: NeonDatabaseOptions = {}): NeonDatabase {
+  return new NeonDatabase(options)
+}

package/src/database/index.ts

@@ -0,0 +1,8 @@
+export {
+  createNeonDatabase,
+  NeonDatabase,
+  neonDatabaseCapabilities,
+  type NeonDatabaseOptions,
+  type NeonSql,
+} from './driver'
+export type { PostgresMigration } from '@avelonjs/postgres/sql'

package/src/identity/cookies.ts

@@ -0,0 +1,54 @@
+import type { RequestCookies } from '@avelonjs/core'
+import type { NeonSession } from './types'
+
+/** Default cookie name used when no project-specific session cookie is configured. */
+export const DEFAULT_SESSION_COOKIE = 'neon-avelon-auth-token'
+
+/** Reads and parses the session cookie, returning null when absent or malformed. */
+export function readSessionCookie(cookies: RequestCookies, cookieName: string): NeonSession | null {
+  const raw = cookies.get(cookieName)
+  if (raw === undefined || raw.length === 0) return null
+  try {
+    const parsed = JSON.parse(raw) as Partial<NeonSession> & { expiresAt?: string }
+    if (
+      typeof parsed.id !== 'string' ||
+      typeof parsed.accessToken !== 'string' ||
+      typeof parsed.refreshToken !== 'string' ||
+      typeof parsed.expiresAt !== 'string'
+    ) {
+      return null
+    }
+    const expiresAt = new Date(parsed.expiresAt)
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() <= Date.now()) return null
+    return {
+      id: parsed.id,
+      accessToken: parsed.accessToken,
+      refreshToken: parsed.refreshToken,
+      expiresAt,
+    }
+  } catch {
+    return null
+  }
+}
+
+/** Writes the session cookie for the current request scope. */
+export function writeSessionCookie(
+  cookies: RequestCookies,
+  cookieName: string,
+  session: NeonSession,
+): void {
+  cookies.set(
+    cookieName,
+    JSON.stringify({
+      id: session.id,
+      accessToken: session.accessToken,
+      refreshToken: session.refreshToken,
+      expiresAt: session.expiresAt.toISOString(),
+    }),
+  )
+}
+
+/** Clears the session cookie for the current request scope. */
+export function clearSessionCookie(cookies: RequestCookies, cookieName: string): void {
+  cookies.delete(cookieName)
+}