@ankhorage/supabase-db 0.2.0

package/src/realtime.ts

@@ -0,0 +1,145 @@
+import type { DbRecord } from '@ankhorage/contracts/db';
+
+import type {
+  DbChangeEvent,
+  DbChangeKind,
+  DbChangeListener,
+  DbCollectionSubscriptionInput,
+  DbRecordSubscriptionInput,
+  DbSubscription,
+  RealtimeDbAdapter,
+  SupabaseRealtimeClient,
+  SupabaseRealtimePayload,
+} from './types.js';
+import { validateIdentifier } from './validation.js';
+
+interface RealtimeApiConfig {
+  readonly client: SupabaseRealtimeClient;
+  readonly defaultSchema: string;
+}
+
+export function createRealtimeApi(config: RealtimeApiConfig): RealtimeDbAdapter['realtime'] {
+  return {
+    subscribeToCollection<TRecord extends object = DbRecord>(
+      input: DbCollectionSubscriptionInput,
+      listener: DbChangeListener<TRecord>,
+    ): DbSubscription {
+      const schema = input.schema ?? config.defaultSchema;
+      const table = validateIdentifier(input.table, 'Realtime table');
+      const channel = config.client
+        .channel(`ankhorage-db:${schema}:${table}`)
+        .on(
+          'postgres_changes',
+          {
+            event: '*',
+            schema,
+            table,
+          },
+          (payload) => {
+            const event = normalizeRealtimeEvent<TRecord>(payload, table, schema);
+
+            if (event !== null) {
+              listener(event);
+            }
+          },
+        )
+        .subscribe();
+
+      return {
+        async unsubscribe(): Promise<void> {
+          await config.client.removeChannel(channel);
+        },
+      };
+    },
+
+    subscribeToRecord<TRecord extends object = DbRecord>(
+      input: DbRecordSubscriptionInput,
+      listener: DbChangeListener<TRecord>,
+    ): DbSubscription {
+      const schema = input.schema ?? config.defaultSchema;
+      const table = validateIdentifier(input.table, 'Realtime table');
+      const idField = validateIdentifier(input.idField ?? 'id', 'Realtime record id field');
+      const channel = config.client
+        .channel(`ankhorage-db:${schema}:${table}:${idField}:${String(input.id)}`)
+        .on(
+          'postgres_changes',
+          {
+            event: '*',
+            schema,
+            table,
+            filter: `${idField}=eq.${String(input.id)}`,
+          },
+          (payload) => {
+            const event = normalizeRealtimeEvent<TRecord>(payload, table, schema);
+
+            if (event !== null) {
+              listener(event);
+            }
+          },
+        )
+        .subscribe();
+
+      return {
+        async unsubscribe(): Promise<void> {
+          await config.client.removeChannel(channel);
+        },
+      };
+    },
+  };
+}
+
+export function normalizeRealtimeEvent<TRecord extends object = DbRecord>(
+  payload: SupabaseRealtimePayload,
+  fallbackTable: string,
+  fallbackSchema: string,
+): DbChangeEvent<TRecord> | null {
+  const kind = normalizeKind(payload.eventType);
+
+  if (kind === null) {
+    return null;
+  }
+
+  const record = normalizeRecord<TRecord>(payload.new);
+  const previousRecord = normalizeRecord<TRecord>(payload.old);
+  const base = {
+    table: payload.table ?? fallbackTable,
+    schema: payload.schema ?? fallbackSchema,
+    kind,
+    record: kind === 'delete' ? null : record,
+    committedAt: payload.commit_timestamp,
+  };
+
+  if (previousRecord === null) {
+    return base;
+  }
+
+  return {
+    ...base,
+    previousRecord,
+  };
+}
+
+function normalizeKind(value: string | undefined): DbChangeKind | null {
+  switch (value) {
+    case 'INSERT':
+      return 'insert';
+    case 'UPDATE':
+      return 'update';
+    case 'DELETE':
+      return 'delete';
+    default:
+      return null;
+  }
+}
+
+function normalizeRecord<TRecord extends object>(value: unknown): TRecord | null {
+  if (!isRecord<TRecord>(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+function isRecord<TRecord extends object>(value: unknown): value is TRecord {
+  return typeof value === 'object' && value !== null;
+}

package/src/types.ts

@@ -0,0 +1,145 @@
+import type { DbAdapter, DbRecord } from '@ankhorage/contracts/db';
+
+interface SupabaseRealtimePostgresChangesFilter {
+  readonly event: 'INSERT' | 'UPDATE' | 'DELETE' | '*';
+  readonly schema: string;
+  readonly table: string;
+  readonly filter?: string;
+}
+
+export interface SupabaseRealtimeChannel {
+  on(
+    type: 'postgres_changes',
+    filter: SupabaseRealtimePostgresChangesFilter,
+    callback: (payload: SupabaseRealtimePayload) => void,
+  ): SupabaseRealtimeChannel;
+  subscribe(callback?: (status: string) => void): SupabaseRealtimeChannel;
+  unsubscribe(): Promise<'ok' | 'timed out' | 'error'>;
+}
+
+export interface SupabaseRealtimeClient {
+  channel(topic: string): SupabaseRealtimeChannel;
+  removeChannel(channel: SupabaseRealtimeChannel): Promise<'ok' | 'timed out' | 'error'>;
+}
+
+export interface SupabaseRealtimePayload {
+  eventType?: string;
+  schema?: string;
+  table?: string;
+  commit_timestamp?: string;
+  new?: unknown;
+  old?: unknown;
+  errors?: string[] | null;
+}
+
+export interface SupabaseDbAdapterOptions {
+  readonly url: string;
+  readonly anonKey: string;
+  readonly schema?: string;
+  readonly fetch?: typeof fetch;
+  readonly realtime?: boolean;
+  readonly realtimeClient?: SupabaseRealtimeClient;
+}
+
+export interface SupabaseDbAdminAdapterOptions {
+  readonly url: string;
+  readonly serviceRoleKey?: string;
+  readonly schema?: string;
+  readonly execute?: boolean;
+  readonly executeSql?: (sql: string) => Promise<DbAdminSqlExecutionResult>;
+}
+
+export interface DbAdminSqlExecutionResult {
+  readonly ok: boolean;
+  readonly error?: {
+    readonly code: string;
+    readonly message: string;
+    readonly cause?: unknown;
+  };
+}
+
+export type SupabaseDbAdapter = DbAdapter & Partial<RealtimeDbAdapter>;
+
+export interface RealtimeDbAdapter {
+  readonly realtime: {
+    subscribeToCollection<TRecord extends object = DbRecord>(
+      input: DbCollectionSubscriptionInput,
+      listener: DbChangeListener<TRecord>,
+    ): DbSubscription;
+    subscribeToRecord<TRecord extends object = DbRecord>(
+      input: DbRecordSubscriptionInput,
+      listener: DbChangeListener<TRecord>,
+    ): DbSubscription;
+  };
+}
+
+export interface DbCollectionSubscriptionInput {
+  readonly table: string;
+  readonly schema?: string;
+}
+
+export interface DbRecordSubscriptionInput extends DbCollectionSubscriptionInput {
+  readonly id: string | number;
+  readonly idField?: string;
+}
+
+export type DbChangeKind = 'insert' | 'update' | 'delete';
+
+export interface DbChangeEvent<TRecord extends object = DbRecord> {
+  readonly table: string;
+  readonly schema: string;
+  readonly kind: DbChangeKind;
+  readonly record: TRecord | null;
+  readonly previousRecord?: TRecord;
+  readonly committedAt?: string;
+}
+
+export type DbChangeListener<TRecord extends object = DbRecord> = (
+  event: DbChangeEvent<TRecord>,
+) => void;
+
+export interface DbSubscription {
+  unsubscribe(): Promise<void>;
+}
+
+export interface SupabaseCollectionDefinition {
+  readonly name: string;
+  readonly fields: readonly SupabaseFieldDefinition[];
+  readonly primaryKey?: string;
+}
+
+export type SupabaseFieldType = 'text' | 'number' | 'boolean' | 'datetime' | 'json' | 'uuid';
+
+export interface SupabaseFieldDefinition {
+  readonly name: string;
+  readonly type: SupabaseFieldType;
+  readonly required?: boolean;
+  readonly unique?: boolean;
+  readonly defaultValue?: string | number | boolean | null;
+}
+
+export interface SupabaseDbAdminAdapter {
+  readonly capabilities: {
+    readonly supportsSchemaGeneration: true;
+    readonly supportsDirectExecution: boolean;
+  };
+  createCollection(input: SupabaseCollectionDefinition): Promise<DbAdminResult>;
+  deleteCollection(input: { readonly name: string }): Promise<DbAdminResult>;
+  generateCreateCollectionSql(input: SupabaseCollectionDefinition): DbAdminResult;
+  generateDeleteCollectionSql(input: { readonly name: string }): DbAdminResult;
+}
+
+export type DbAdminResult =
+  | {
+      readonly ok: true;
+      readonly sql: string;
+      readonly executed: boolean;
+    }
+  | {
+      readonly ok: false;
+      readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly cause?: unknown;
+      };
+    };

package/src/validation.ts

@@ -0,0 +1,57 @@
+import type { DbFilter } from '@ankhorage/contracts/db';
+
+export function validateUrl(url: string): string {
+  const trimmed = url.trim();
+
+  if (trimmed.length === 0) {
+    throw new TypeError('Supabase URL is required.');
+  }
+
+  try {
+    new URL(trimmed);
+  } catch {
+    throw new TypeError('Supabase URL must be a valid URL.');
+  }
+
+  return trimmed.replace(/\/+$/, '');
+}
+
+export function validateKey(value: string, label: string): string {
+  const trimmed = value.trim();
+
+  if (trimmed.length === 0) {
+    throw new TypeError(`${label} is required.`);
+  }
+
+  return trimmed;
+}
+
+export function validateIdentifier(value: string, label: string): string {
+  const trimmed = value.trim();
+
+  if (trimmed.length === 0) {
+    throw new TypeError(`${label} is required.`);
+  }
+
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed)) {
+    throw new TypeError(`${label} must be a valid SQL identifier.`);
+  }
+
+  return trimmed;
+}
+
+export function validateFilters(filters: readonly DbFilter[], label: string): void {
+  if (filters.length === 0) {
+    throw new TypeError(`${label} requires at least one filter.`);
+  }
+
+  for (const filter of filters) {
+    validateIdentifier(filter.field, 'Filter field');
+  }
+}
+
+export function quoteIdentifier(value: string): string {
+  const identifier = validateIdentifier(value, 'SQL identifier');
+
+  return `"${identifier.replaceAll('"', '""')}"`;
+}