@avelonjs/supabase 0.1.0 → 0.3.1

package/src/database/driver.ts

@@ -1,6 +1,6 @@
-import { SQL } from 'bun'
 import {
   Invalid,
+  Unavailable,
   type DatabaseDriver,
   type MigrationPlan,
   type MigrationStatus,
@@ -14,17 +14,18 @@ import {
   applyMigrations,
   assertQueryAgainstSchema,
   combinedPredicate,
-  loadSchemaCache,
   planMigrations,
   rollbackMigrations,
   statusMigrations,
   validateQueryIR,
   type PostgresMigration,
   type SchemaCache,
-} from '@avelonjs/postgres'
+  type SqlBatchRunner,
+} from '@avelonjs/postgres/sql'
 import { compilePostgrest } from './compile'
 import { mapPostgrestError } from './errors'
 import { resetSupabaseAssayFixtures } from './fixtures'
+import { loadSchemaCacheFromRest } from './schema-rest'
 import { compileAllWardPolicies, type WardPolicy } from './wards'
 
 /** Exact capability declaration for the Supabase/PostgREST database driver. */
@@ -46,8 +47,12 @@ export interface SupabaseDatabaseOptions {
   restUrl?: string
   /** Service-role JWT used for privileged conformance and sync operations. */
   serviceRoleKey?: string
-  /** Direct Postgres URL for fixtures, schema cache, migrations, and RLS sync. */
-  databaseUrl?: string
+  /**
+   * Statement runner over a direct Postgres connection, used by migrations, fixtures and ward
+   * sync. Absent on a runtime with no Postgres socket, where those operations raise
+   * {@link Unavailable} and the PostgREST request path still works.
+   */
+  admin?: SqlBatchRunner
   /** Configured connection name. */
   instance?: string
   /** Ward policies applied by `syncWards()`. */
@@ -88,7 +93,9 @@ function projectRow(row: Row, select: string[] | '*', relations: readonly Relati
   const output: Row = {}
   const columns =
     select === '*'
-      ? Object.keys(row).filter((column) => !relations.some((relation) => relation.relation === column))
+      ? 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]
@@ -120,7 +127,7 @@ export class SupabaseDatabase
 
   readonly #restUrl: string
   readonly #serviceRoleKey: string
-  readonly #sql: SQL
+  readonly #admin: SqlBatchRunner | undefined
   readonly #wards: readonly WardPolicy[]
   readonly #migrations: readonly PostgresMigration[]
   #schema: SchemaCache | undefined
@@ -130,7 +137,7 @@ export class SupabaseDatabase
     this.instance = options.instance ?? 'default'
     this.#restUrl = (options.restUrl ?? defaultRestUrl()).replace(/\/$/, '')
     this.#serviceRoleKey = options.serviceRoleKey ?? defaultServiceRoleKey()
-    this.#sql = new SQL(options.databaseUrl ?? defaultDatabaseUrl())
+    this.#admin = options.admin
     this.#wards = options.wards ?? []
     this.#migrations = options.migrations ?? []
   }
@@ -147,14 +154,26 @@ export class SupabaseDatabase
 
   /** Recreates assay fixtures and reloads the PostgREST schema cache. */
   async resetFixtures(): Promise<void> {
-    await resetSupabaseAssayFixtures(this.#sql)
+    await resetSupabaseAssayFixtures(this.#requireAdmin('resetFixtures'))
     this.#schema = undefined
     await this.#waitForSchema()
   }
 
-  /** Closes the direct Postgres admin client. */
+  /** Releases the direct Postgres admin client when one was configured. */
   async close(): Promise<void> {
-    await this.#sql.close()
+    await this.#admin?.close?.()
+  }
+
+  #requireAdmin(operation: string): SqlBatchRunner {
+    if (this.#admin === undefined) {
+      throw new Unavailable(
+        `${operation} needs a direct Postgres connection. Build the driver through ` +
+          '`@avelonjs/supabase/database/bun` under the Bun CLI; the PostgREST request path ' +
+          'has no socket to run it over.',
+        { metadata: { service: 'database' } },
+      )
+    }
+    return this.#admin
   }
 
   async execute<TRow = Record<string, unknown>>(query: QueryIR): Promise<QueryResult<TRow>> {
@@ -202,35 +221,40 @@ export class SupabaseDatabase
 
   /** Produces the pending migration plan from the direct Postgres connection. */
   async plan(): Promise<MigrationPlan> {
-    return planMigrations(this.#sql, this.#migrations)
+    return planMigrations(this.#requireAdmin('plan'), this.#migrations)
   }
 
   /** Applies pending driver-owned migrations. */
   async apply(): Promise<readonly MigrationStatus[]> {
-    return applyMigrations(this.#sql, this.#migrations)
+    return applyMigrations(this.#requireAdmin('apply'), this.#migrations)
   }
 
   /** Rolls back applied migration batches. */
   async rollback(steps?: number): Promise<readonly MigrationStatus[]> {
-    return rollbackMigrations(this.#sql, this.#migrations, steps)
+    return rollbackMigrations(this.#requireAdmin('rollback'), this.#migrations, steps)
   }
 
   /** Returns all migration states. */
   async status(): Promise<readonly MigrationStatus[]> {
-    return statusMigrations(this.#sql, this.#migrations)
+    return statusMigrations(this.#requireAdmin('status'), this.#migrations)
   }
 
   /** Compiles registered wards into Postgres RLS policies and applies them. */
   async syncWards(): Promise<void> {
-    const statements = compileAllWardPolicies(this.#wards)
-    for (const statement of statements) {
-      await this.#sql.unsafe(statement)
+    const admin = this.#requireAdmin('syncWards')
+    for (const statement of compileAllWardPolicies(this.#wards)) {
+      await admin.unsafe(statement)
     }
-    await this.#sql.unsafe(`NOTIFY pgrst, 'reload schema'`)
+    await admin.unsafe(`NOTIFY pgrst, 'reload schema'`)
   }
 
   async #schemaCache(): Promise<SchemaCache> {
-    if (this.#schema === undefined) this.#schema = await loadSchemaCache(this.#sql)
+    if (this.#schema === undefined) {
+      this.#schema = await loadSchemaCacheFromRest(
+        this.#restUrl,
+        this.#authHeaders(this.#serviceRoleKey),
+      )
+    }
     return this.#schema
   }
 
@@ -244,9 +268,12 @@ export class SupabaseDatabase
     }
 
     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`] } },
-      })
+      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') {
@@ -279,7 +306,10 @@ export class SupabaseDatabase
   }
 
   async #executeCount(ir: QueryIR, predicate: Predicate, bearerToken: string): Promise<number> {
-    const compiled = compilePostgrest({ ...ir, mode: 'count', select: [], order: [], relations: [] }, predicate)
+    const compiled = compilePostgrest(
+      { ...ir, mode: 'count', select: [], order: [], relations: [] },
+      predicate,
+    )
     const url = new URL(`${this.#restUrl}${compiled.path}`)
     if (compiled.query) url.search = compiled.query
     this.#roundTrips += 1
@@ -305,11 +335,7 @@ export class SupabaseDatabase
     return Number(total)
   }
 
-  async #executePrimitive(
-    ir: QueryIR,
-    predicate: Predicate,
-    bearerToken: string,
-  ): Promise<Row[]> {
+  async #executePrimitive(ir: QueryIR, predicate: Predicate, bearerToken: string): Promise<Row[]> {
     const compiled = compilePostgrest(ir, predicate)
     const path = compiled.query ? `${compiled.path}?${compiled.query}` : compiled.path
     const rows = await this.#requestRows(path, {

package/src/database/errors.ts

@@ -16,11 +16,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  *
  * Unique violations become `Conflict`. Missing tables, columns, and routines become `Invalid`.
  */
-export function mapPostgrestError(
-  status: number,
-  bodyText: string,
-  operation: string,
-): never {
+export function mapPostgrestError(status: number, bodyText: string, operation: string): never {
   let parsed: PostgrestErrorBody | undefined
   try {
     const value = JSON.parse(bodyText) as unknown
@@ -30,8 +26,7 @@ export function mapPostgrestError(
   }
 
   const code = parsed?.code
-  const message =
-    parsed?.message ?? (bodyText || `PostgREST ${operation} failed (${status})`)
+  const message = parsed?.message ?? (bodyText || `PostgREST ${operation} failed (${status})`)
 
   if (code === '23505' || /duplicate key value/i.test(message)) {
     throw new Conflict(message, {

package/src/database/fixtures.ts

@@ -1,4 +1,4 @@
-import type { SQL } from 'bun'
+import type { SqlRunner } from '@avelonjs/postgres/sql'
 
 /** SQL that provisions assay fixtures, upsert RPC, and a minimal auth.uid() helper. */
 export const SUPABASE_ASSAY_FIXTURE_SQL = `
@@ -201,6 +201,6 @@ NOTIFY pgrst, 'reload schema';
 `
 
 /** Provisions empty assay fixtures and helper routines for live Supabase database tests. */
-export async function resetSupabaseAssayFixtures(sql: SQL): Promise<void> {
-  await sql.unsafe(SUPABASE_ASSAY_FIXTURE_SQL)
+export async function resetSupabaseAssayFixtures(runner: SqlRunner): Promise<void> {
+  await runner.unsafe(SUPABASE_ASSAY_FIXTURE_SQL)
 }

package/src/database/index.ts

@@ -6,6 +6,7 @@ export {
   type SupabaseDatabaseOptions,
 } from './driver'
 export { mapPostgrestError, SUPABASE_DATABASE_ERROR_MAP } from './errors'
+export { loadSchemaCacheFromRest } from './schema-rest'
 export { resetSupabaseAssayFixtures, SUPABASE_ASSAY_FIXTURE_SQL } from './fixtures'
 export { combinedPredicate, normalizePredicate } from './normalize'
 export {
@@ -14,4 +15,4 @@ export {
   compileWardPolicySql,
   type WardPolicy,
 } from './wards'
-export type { PostgresMigration } from '@avelonjs/postgres'
+export type { PostgresMigration } from '@avelonjs/postgres/sql'

package/src/database/normalize.ts

@@ -1 +1 @@
-export { combinedPredicate, normalizePredicate } from '@avelonjs/postgres'
+export { combinedPredicate, normalizePredicate } from '@avelonjs/postgres/sql'

package/src/database/schema-rest.ts

@@ -0,0 +1,54 @@
+import type { SchemaCache } from '@avelonjs/postgres/sql'
+import { mapPostgrestError } from './errors'
+
+interface OpenApiDefinition {
+  properties?: Record<string, unknown>
+}
+
+interface OpenApiDocument {
+  definitions?: Record<string, OpenApiDefinition>
+}
+
+function asDocument(payload: unknown): OpenApiDocument {
+  if (payload === null || typeof payload !== 'object') return {}
+  const definitions = Reflect.get(payload, 'definitions')
+  if (definitions === null || typeof definitions !== 'object') return {}
+  return { definitions: definitions as Record<string, OpenApiDefinition> }
+}
+
+function columnsOf(definition: OpenApiDefinition): Set<string> {
+  const properties = definition.properties
+  if (properties === undefined || properties === null) return new Set()
+  return new Set(Object.keys(properties))
+}
+
+/**
+ * Reads the table and column set from PostgREST's OpenAPI document at the REST root.
+ *
+ * PostgREST filters that document by the role in the bearer token, so callers pass the same token
+ * their queries use. A token that cannot see a table would otherwise produce a cache that rejects
+ * queries the same token is allowed to run.
+ */
+export async function loadSchemaCacheFromRest(
+  restUrl: string,
+  headers: Readonly<Record<string, string>>,
+): Promise<SchemaCache> {
+  const response = await fetch(`${restUrl}/`, {
+    headers: { ...headers, Accept: 'application/openapi+json' },
+  })
+  const text = await response.text()
+  if (!response.ok) mapPostgrestError(response.status, text, 'schema.load')
+
+  let payload: unknown
+  try {
+    payload = JSON.parse(text)
+  } catch {
+    mapPostgrestError(response.status, text, 'schema.load')
+  }
+
+  const cache: SchemaCache = new Map()
+  for (const [table, definition] of Object.entries(asDocument(payload).definitions ?? {})) {
+    cache.set(table, columnsOf(definition))
+  }
+  return cache
+}

package/src/database/wards.ts

@@ -1,5 +1,5 @@
 import { Invalid, type CompareOp, type Predicate } from '@avelonjs/core'
-import { normalizePredicate } from '@avelonjs/postgres'
+import { normalizePredicate } from '@avelonjs/postgres/sql'
 
 /** One ward policy synchronized into Postgres RLS. */
 export interface WardPolicy {
@@ -83,7 +83,12 @@ function compileValue(value: unknown): string {
 }
 
 function isClaim(value: unknown): value is { claim: string } {
-  return typeof value === 'object' && value !== null && 'claim' in value && typeof (value as { claim: unknown }).claim === 'string'
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'claim' in value &&
+    typeof (value as { claim: unknown }).claim === 'string'
+  )
 }
 
 /** Builds DROP/CREATE POLICY statements for one ward policy. */
@@ -94,18 +99,13 @@ export function compileWardPolicySql(policy: WardPolicy): string[] {
   const command = policy.command.toUpperCase()
   const statements = [`DROP POLICY IF EXISTS ${name} ON ${table}`]
 
-  const using =
-    policy.using === undefined ? undefined : compileWardPredicate(policy.using)
-  const check =
-    policy.check === undefined ? undefined : compileWardPredicate(policy.check)
+  const using = policy.using === undefined ? undefined : compileWardPredicate(policy.using)
+  const check = policy.check === undefined ? undefined : compileWardPredicate(policy.check)
 
   if (policy.command === 'insert' && check === undefined) {
     invalid(`Insert ward policy '${policy.name}' requires a check predicate.`)
   }
-  if (
-    (policy.command === 'select' || policy.command === 'delete') &&
-    using === undefined
-  ) {
+  if ((policy.command === 'select' || policy.command === 'delete') && using === undefined) {
     invalid(`Ward policy '${policy.name}' requires a using predicate.`)
   }