@ankhorage/supabase-db 0.2.0

package/src/admin.ts

@@ -0,0 +1,205 @@
+import type {
+  DbAdminResult,
+  SupabaseCollectionDefinition,
+  SupabaseDbAdminAdapter,
+  SupabaseDbAdminAdapterOptions,
+  SupabaseFieldDefinition,
+} from './types.js';
+import { quoteIdentifier, validateKey, validateUrl } from './validation.js';
+
+interface NormalizedAdminConfig {
+  readonly url: string;
+  readonly schema: string;
+  readonly serviceRoleKey?: string;
+  readonly execute: boolean;
+  readonly executeSql?: SupabaseDbAdminAdapterOptions['executeSql'];
+}
+
+export function createSupabaseDbAdminAdapter(
+  options: SupabaseDbAdminAdapterOptions,
+): SupabaseDbAdminAdapter {
+  const config = normalizeAdminConfig(options);
+
+  return {
+    capabilities: {
+      supportsSchemaGeneration: true,
+      supportsDirectExecution: config.execute && config.executeSql !== undefined,
+    },
+
+    async createCollection(input: SupabaseCollectionDefinition): Promise<DbAdminResult> {
+      const generated = generateCreateCollectionSql(input, config.schema);
+
+      if (!generated.ok || !config.execute) {
+        return generated;
+      }
+
+      return executeSql(config, generated.sql);
+    },
+
+    async deleteCollection(input: { readonly name: string }): Promise<DbAdminResult> {
+      const generated = generateDeleteCollectionSql(input, config.schema);
+
+      if (!generated.ok || !config.execute) {
+        return generated;
+      }
+
+      return executeSql(config, generated.sql);
+    },
+
+    generateCreateCollectionSql(input: SupabaseCollectionDefinition): DbAdminResult {
+      return generateCreateCollectionSql(input, config.schema);
+    },
+
+    generateDeleteCollectionSql(input: { readonly name: string }): DbAdminResult {
+      return generateDeleteCollectionSql(input, config.schema);
+    },
+  };
+}
+
+function normalizeAdminConfig(options: SupabaseDbAdminAdapterOptions): NormalizedAdminConfig {
+  const normalized: NormalizedAdminConfig = {
+    url: validateUrl(options.url),
+    schema: options.schema ?? 'public',
+    execute: options.execute ?? false,
+    executeSql: options.executeSql,
+  };
+
+  if (options.serviceRoleKey === undefined) {
+    return normalized;
+  }
+
+  return {
+    ...normalized,
+    serviceRoleKey: validateKey(options.serviceRoleKey, 'Supabase service role key'),
+  };
+}
+
+function generateCreateCollectionSql(
+  input: SupabaseCollectionDefinition,
+  schemaValue: string,
+): DbAdminResult {
+  try {
+    const schema = quoteIdentifier(schemaValue);
+    const table = quoteIdentifier(input.name);
+    const primaryKey = input.primaryKey ?? 'id';
+    const fields = input.fields.map((field) => formatField(field));
+    const primaryKeyFieldExists = input.fields.some((field) => field.name === primaryKey);
+    const columns = primaryKeyFieldExists
+      ? fields
+      : [`${quoteIdentifier(primaryKey)} uuid primary key default gen_random_uuid()`, ...fields];
+
+    if (columns.length === 0) {
+      return createAdminError('validation_error', 'A collection requires at least one field.');
+    }
+
+    return {
+      ok: true,
+      sql: `create schema if not exists ${schema};\ncreate table if not exists ${schema}.${table} (\n  ${columns.join(',\n  ')}\n);`,
+      executed: false,
+    };
+  } catch (error) {
+    return createAdminError('validation_error', 'Invalid collection definition.', error);
+  }
+}
+
+function generateDeleteCollectionSql(
+  input: { readonly name: string },
+  schemaValue: string,
+): DbAdminResult {
+  try {
+    const schema = quoteIdentifier(schemaValue);
+    const table = quoteIdentifier(input.name);
+
+    return {
+      ok: true,
+      sql: `drop table if exists ${schema}.${table};`,
+      executed: false,
+    };
+  } catch (error) {
+    return createAdminError('validation_error', 'Invalid collection name.', error);
+  }
+}
+
+async function executeSql(config: NormalizedAdminConfig, sql: string): Promise<DbAdminResult> {
+  if (config.executeSql === undefined) {
+    return createAdminError(
+      'execution_not_configured',
+      'Schema execution requires an executeSql callback.',
+    );
+  }
+
+  if (config.serviceRoleKey === undefined) {
+    return createAdminError(
+      'missing_service_role_key',
+      'Schema execution requires a service role key in privileged environments only.',
+    );
+  }
+
+  const result = await config.executeSql(sql);
+
+  if (!result.ok) {
+    return {
+      ok: false,
+      error: result.error ?? {
+        code: 'provider_error',
+        message: 'Supabase schema execution failed.',
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    sql,
+    executed: true,
+  };
+}
+
+function formatField(field: SupabaseFieldDefinition): string {
+  const name = quoteIdentifier(field.name);
+  const type = mapFieldType(field.type);
+  const required = field.required === true ? ' not null' : '';
+  const unique = field.unique === true ? ' unique' : '';
+  const defaultValue = formatDefaultValue(field.defaultValue);
+
+  return `${name} ${type}${required}${unique}${defaultValue}`;
+}
+
+function mapFieldType(type: SupabaseFieldDefinition['type']): string {
+  switch (type) {
+    case 'text':
+      return 'text';
+    case 'number':
+      return 'double precision';
+    case 'boolean':
+      return 'boolean';
+    case 'datetime':
+      return 'timestamptz';
+    case 'json':
+      return 'jsonb';
+    case 'uuid':
+      return 'uuid';
+  }
+}
+
+function formatDefaultValue(value: SupabaseFieldDefinition['defaultValue']): string {
+  if (value === undefined) {
+    return '';
+  }
+
+  if (value === null) {
+    return ' default null';
+  }
+
+  if (typeof value === 'string') {
+    return ` default '${value.replaceAll("'", "''")}'`;
+  }
+
+  return ` default ${String(value)}`;
+}
+
+function createAdminError(code: string, message: string, cause?: unknown): DbAdminResult {
+  return {
+    ok: false,
+    error: cause === undefined ? { code, message } : { code, message, cause },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,66 @@
+import type { DbAdapterError } from '@ankhorage/contracts/db';
+
+export function createDbError(code: string, message: string, cause?: unknown): DbAdapterError {
+  return cause === undefined ? { code, message } : { code, message, cause };
+}
+
+export function mapNetworkError(error: unknown): DbAdapterError {
+  return createDbError('network_error', 'Supabase Database request failed.', error);
+}
+
+export function mapHttpError(status: number, body: unknown): DbAdapterError {
+  const providerMessage = readProviderMessage(body);
+
+  if (status === 401 || status === 403) {
+    return createDbError(
+      'permission_denied',
+      providerMessage ?? 'Supabase Database denied the request.',
+      body,
+    );
+  }
+
+  if (status === 404) {
+    return createDbError(
+      'missing_table',
+      providerMessage ?? 'Supabase Database resource was not found.',
+      body,
+    );
+  }
+
+  if (status >= 400 && status < 500) {
+    return createDbError(
+      'invalid_query',
+      providerMessage ?? 'Supabase Database rejected the query.',
+      body,
+    );
+  }
+
+  return createDbError(
+    'provider_error',
+    providerMessage ?? 'Supabase Database returned an unexpected error.',
+    body,
+  );
+}
+
+function readProviderMessage(body: unknown): string | undefined {
+  if (!isRecord(body)) {
+    return undefined;
+  }
+
+  const { message } = body;
+  const { error } = body;
+
+  if (typeof message === 'string' && message.trim().length > 0) {
+    return message;
+  }
+
+  if (typeof error === 'string' && error.trim().length > 0) {
+    return error;
+  }
+
+  return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { createSupabaseDbAdapter } from './adapter.js';
+export { createSupabaseDbAdminAdapter } from './admin.js';
+export { normalizeRealtimeEvent } from './realtime.js';
+export type {
+  DbAdminResult,
+  DbAdminSqlExecutionResult,
+  DbChangeEvent,
+  DbChangeKind,
+  DbChangeListener,
+  DbCollectionSubscriptionInput,
+  DbRecordSubscriptionInput,
+  DbSubscription,
+  RealtimeDbAdapter,
+  SupabaseCollectionDefinition,
+  SupabaseDbAdapter,
+  SupabaseDbAdapterOptions,
+  SupabaseDbAdminAdapter,
+  SupabaseDbAdminAdapterOptions,
+  SupabaseFieldDefinition,
+  SupabaseFieldType,
+  SupabaseRealtimeClient,
+  SupabaseRealtimePayload,
+} from './types.js';

package/src/query.ts

@@ -0,0 +1,122 @@
+import type { DbFilter, DbPage, DbSelectInput, DbSort } from '@ankhorage/contracts/db';
+
+import { validateIdentifier } from './validation.js';
+
+export function buildSelectUrl(baseUrl: string, input: DbSelectInput): URL {
+  const table = validateIdentifier(input.table, 'Table');
+  const url = new URL(`${baseUrl}/rest/v1/${table}`);
+
+  url.searchParams.set('select', formatColumns(input.columns));
+
+  applyFilters(url, input.filters ?? []);
+  applySort(url, input.sort ?? []);
+  applyPage(url, input.page);
+
+  return url;
+}
+
+export function buildMutationUrl(
+  baseUrl: string,
+  tableValue: string,
+  filters: readonly DbFilter[],
+): URL {
+  const table = validateIdentifier(tableValue, 'Table');
+  const url = new URL(`${baseUrl}/rest/v1/${table}`);
+
+  applyFilters(url, filters);
+
+  return url;
+}
+
+function applyFilters(url: URL, filters: readonly DbFilter[]): void {
+  for (const filter of filters) {
+    const field = validateIdentifier(filter.field, 'Filter field');
+    url.searchParams.append(field, formatFilter(filter));
+  }
+}
+
+function applySort(url: URL, sort: readonly DbSort[]): void {
+  if (sort.length === 0) {
+    return;
+  }
+
+  const order = sort
+    .map((item) => {
+      const field = validateIdentifier(item.field, 'Sort field');
+      return `${field}.${item.direction ?? 'asc'}`;
+    })
+    .join(',');
+
+  url.searchParams.set('order', order);
+}
+
+function applyPage(url: URL, page: DbPage | undefined): void {
+  if (page?.limit !== undefined) {
+    url.searchParams.set('limit', String(page.limit));
+  }
+
+  if (page?.offset !== undefined) {
+    url.searchParams.set('offset', String(page.offset));
+  }
+}
+
+function formatColumns(columns: readonly string[] | undefined): string {
+  if (columns === undefined || columns.length === 0) {
+    return '*';
+  }
+
+  return columns.map((column) => validateIdentifier(column, 'Column')).join(',');
+}
+
+function formatFilter(filter: DbFilter): string {
+  switch (filter.operator) {
+    case 'eq':
+      return `eq.${formatValue(filter.value)}`;
+    case 'neq':
+      return `neq.${formatValue(filter.value)}`;
+    case 'gt':
+      return `gt.${formatValue(filter.value)}`;
+    case 'gte':
+      return `gte.${formatValue(filter.value)}`;
+    case 'lt':
+      return `lt.${formatValue(filter.value)}`;
+    case 'lte':
+      return `lte.${formatValue(filter.value)}`;
+    case 'in':
+      return `in.(${formatInValue(filter.value)})`;
+    case 'contains':
+      return `cs.${formatValue(filter.value)}`;
+    case 'startsWith':
+      return `like.${formatLikeValue(filter.value)}*`;
+    case 'endsWith':
+      return `like.*${formatLikeValue(filter.value)}`;
+  }
+}
+
+function formatInValue(value: unknown): string {
+  if (!Array.isArray(value)) {
+    return formatValue(value);
+  }
+
+  return value.map((item) => formatValue(item)).join(',');
+}
+
+function formatLikeValue(value: unknown): string {
+  return String(value).replaceAll('*', '\\*');
+}
+
+function formatValue(value: unknown): string {
+  if (value === null) {
+    return 'null';
+  }
+
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  return JSON.stringify(value);
+}

package/src/realtime.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createSupabaseDbAdapter } from './adapter.js';
+import { normalizeRealtimeEvent } from './realtime.js';
+import type {
+  SupabaseRealtimeChannel,
+  SupabaseRealtimeClient,
+  SupabaseRealtimePayload,
+} from './types.js';
+
+interface PostRecord {
+  readonly id: string;
+  readonly title: string;
+}
+
+describe('normalizeRealtimeEvent', () => {
+  test('normalizes insert payloads', () => {
+    const event = normalizeRealtimeEvent<PostRecord>(
+      {
+        eventType: 'INSERT',
+        schema: 'public',
+        table: 'posts',
+        commit_timestamp: '2026-05-12T10:00:00Z',
+        new: { id: 'post-1', title: 'Hello' },
+      },
+      'fallback',
+      'public',
+    );
+
+    expect(event).toEqual({
+      table: 'posts',
+      schema: 'public',
+      kind: 'insert',
+      record: { id: 'post-1', title: 'Hello' },
+      committedAt: '2026-05-12T10:00:00Z',
+    });
+  });
+
+  test('normalizes update payloads with previous record', () => {
+    const event = normalizeRealtimeEvent<PostRecord>(
+      {
+        eventType: 'UPDATE',
+        new: { id: 'post-1', title: 'Updated' },
+        old: { id: 'post-1', title: 'Old' },
+      },
+      'posts',
+      'public',
+    );
+
+    expect(event).toEqual({
+      table: 'posts',
+      schema: 'public',
+      kind: 'update',
+      record: { id: 'post-1', title: 'Updated' },
+      previousRecord: { id: 'post-1', title: 'Old' },
+      committedAt: undefined,
+    });
+  });
+
+  test('normalizes delete payloads to a null current record', () => {
+    const event = normalizeRealtimeEvent<PostRecord>(
+      {
+        eventType: 'DELETE',
+        old: { id: 'post-1', title: 'Deleted' },
+      },
+      'posts',
+      'public',
+    );
+
+    expect(event).toEqual({
+      table: 'posts',
+      schema: 'public',
+      kind: 'delete',
+      record: null,
+      previousRecord: { id: 'post-1', title: 'Deleted' },
+      committedAt: undefined,
+    });
+  });
+
+  test('ignores unknown realtime events', () => {
+    const event = normalizeRealtimeEvent<PostRecord>({ eventType: 'TRUNCATE' }, 'posts', 'public');
+
+    expect(event).toBeNull();
+  });
+});
+
+describe('realtime adapter capability', () => {
+  test('subscribes and cleans up collection channels', async () => {
+    const client = createFakeRealtimeClient();
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      realtime: true,
+      realtimeClient: client,
+      fetch: () => Promise.resolve(new Response('[]')),
+    });
+
+    const received: unknown[] = [];
+    const subscription = adapter.realtime?.subscribeToCollection<PostRecord>(
+      { table: 'posts' },
+      (event) => {
+        received.push(event);
+      },
+    );
+
+    client.emit({
+      eventType: 'INSERT',
+      table: 'posts',
+      schema: 'public',
+      new: { id: '1', title: 'A' },
+    });
+    await subscription?.unsubscribe();
+
+    expect(received).toHaveLength(1);
+    expect(client.removedChannels).toBe(1);
+  });
+
+  test('subscribes to a specific record using a Supabase filter', () => {
+    const client = createFakeRealtimeClient();
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      realtime: true,
+      realtimeClient: client,
+      fetch: () => Promise.resolve(new Response('[]')),
+    });
+
+    adapter.realtime?.subscribeToRecord<PostRecord>(
+      { table: 'posts', id: 'post-1' },
+      () => undefined,
+    );
+
+    expect(client.lastFilter?.filter).toBe('id=eq.post-1');
+  });
+});
+
+function createFakeRealtimeClient(): SupabaseRealtimeClient & {
+  emit(payload: SupabaseRealtimePayload): void;
+  readonly removedChannels: number;
+  readonly lastFilter: { readonly filter?: string } | undefined;
+} {
+  let callback: ((payload: SupabaseRealtimePayload) => void) | undefined;
+  let removedChannels = 0;
+  let lastFilter: { readonly filter?: string } | undefined;
+
+  const channel: SupabaseRealtimeChannel = {
+    on(_type, filter, nextCallback) {
+      lastFilter = { filter: filter.filter };
+      callback = nextCallback;
+      return channel;
+    },
+    subscribe() {
+      return channel;
+    },
+    unsubscribe() {
+      return Promise.resolve<'ok'>('ok');
+    },
+  };
+
+  return {
+    channel() {
+      return channel;
+    },
+    removeChannel() {
+      removedChannels += 1;
+      return Promise.resolve<'ok'>('ok');
+    },
+    emit(payload: SupabaseRealtimePayload) {
+      callback?.(payload);
+    },
+    get removedChannels() {
+      return removedChannels;
+    },
+    get lastFilter() {
+      return lastFilter;
+    },
+  };
+}