@ankhorage/supabase-db 0.2.0

package/src/adapter.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createSupabaseDbAdapter } from './adapter.js';
+
+interface FetchCall {
+  readonly url: string;
+  readonly init: RequestInit | undefined;
+}
+
+interface PostRecord {
+  readonly id: string;
+  readonly title: string;
+}
+
+describe('createSupabaseDbAdapter', () => {
+  test('maps select input to Supabase PostgREST query params', async () => {
+    const calls: FetchCall[] = [];
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: (input, init) => {
+        calls.push({ url: fetchInputToString(input), init });
+        return Promise.resolve(jsonResponse([{ id: 'post-1', title: 'Hello' }]));
+      },
+    });
+
+    const result = await adapter.select<PostRecord>({
+      table: 'posts',
+      columns: ['id', 'title'],
+      filters: [{ field: 'title', operator: 'startsWith', value: 'Hel' }],
+      sort: [{ field: 'title', direction: 'desc' }],
+      page: { limit: 10, offset: 5 },
+    });
+
+    expect(result).toEqual({ ok: true, data: [{ id: 'post-1', title: 'Hello' }] });
+    expect(calls).toHaveLength(1);
+
+    const url = new URL(calls[0]?.url ?? 'https://invalid.test');
+    expect(url.pathname).toBe('/rest/v1/posts');
+    expect(url.searchParams.get('select')).toBe('id,title');
+    expect(url.searchParams.get('title')).toBe('like.Hel*');
+    expect(url.searchParams.get('order')).toBe('title.desc');
+    expect(url.searchParams.get('limit')).toBe('10');
+    expect(url.searchParams.get('offset')).toBe('5');
+    expect(readHeader(calls[0]?.init, 'apikey')).toBe('anon');
+    expect(readHeader(calls[0]?.init, 'Prefer')).toBe('return=representation');
+  });
+
+  test('finds records by id', async () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: () => Promise.resolve(jsonResponse([{ id: 'post-1', title: 'Hello' }])),
+    });
+
+    const result = await adapter.findById<PostRecord>({ table: 'posts', id: 'post-1' });
+
+    expect(result).toEqual({ ok: true, data: { id: 'post-1', title: 'Hello' } });
+  });
+
+  test('normalizes empty findById result to null', async () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: () => Promise.resolve(jsonResponse([])),
+    });
+
+    const result = await adapter.findById<PostRecord>({ table: 'posts', id: 'missing' });
+
+    expect(result).toEqual({ ok: true, data: null });
+  });
+
+  test('maps insert values to POST with returning representation', async () => {
+    const calls: FetchCall[] = [];
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: (input, init) => {
+        calls.push({ url: fetchInputToString(input), init });
+        return Promise.resolve(jsonResponse([{ id: 'post-1', title: 'Hello' }]));
+      },
+    });
+
+    const result = await adapter.insert<PostRecord>({
+      table: 'posts',
+      values: { id: 'post-1', title: 'Hello' },
+    });
+
+    expect(result.ok).toBe(true);
+    expect(calls[0]?.init?.method).toBe('POST');
+    expect(calls[0]?.init?.body).toBe(JSON.stringify({ id: 'post-1', title: 'Hello' }));
+  });
+
+  test('requires filters for update', async () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: () => Promise.resolve(jsonResponse([])),
+    });
+
+    const result = await adapter.update<PostRecord>({
+      table: 'posts',
+      values: { title: 'Updated' },
+      filters: [],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.error.code : '').toBe('validation_error');
+  });
+
+  test('requires filters for delete', async () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: () => Promise.resolve(jsonResponse([])),
+    });
+
+    const result = await adapter.delete<PostRecord>({ table: 'posts', filters: [] });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.error.code : '').toBe('validation_error');
+  });
+
+  test('normalizes provider errors', async () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      fetch: () => Promise.resolve(jsonResponse({ message: 'permission denied' }, 403)),
+    });
+
+    const result = await adapter.select<PostRecord>({ table: 'posts' });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.error.code : '').toBe('permission_denied');
+  });
+
+  test('exposes realtime capability only when configured with a client', () => {
+    const adapter = createSupabaseDbAdapter({
+      url: 'https://example.supabase.co',
+      anonKey: 'anon',
+      realtime: false,
+      fetch: () => Promise.resolve(jsonResponse([])),
+    });
+
+    expect(adapter.capabilities?.supportsRealtime).toBe(false);
+    expect('realtime' in adapter).toBe(false);
+  });
+});
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+function fetchInputToString(input: RequestInfo | URL): string {
+  if (typeof input === 'string') {
+    return input;
+  }
+
+  if (input instanceof URL) {
+    return input.toString();
+  }
+
+  return input.url;
+}
+
+function readHeader(init: RequestInit | undefined, name: string): string | null {
+  const headers = new Headers(init?.headers);
+
+  return headers.get(name);
+}

package/src/adapter.ts

@@ -0,0 +1,249 @@
+import type {
+  DbAdapter,
+  DbDeleteInput,
+  DbFilter,
+  DbFindByIdInput,
+  DbInsertInput,
+  DbRecord,
+  DbResult,
+  DbSelectInput,
+  DbUpdateInput,
+} from '@ankhorage/contracts/db';
+
+import { createDbError, mapHttpError, mapNetworkError } from './errors.js';
+import { buildMutationUrl, buildSelectUrl } from './query.js';
+import { createRealtimeApi } from './realtime.js';
+import type { SupabaseDbAdapter, SupabaseDbAdapterOptions } from './types.js';
+import { validateFilters, validateKey, validateUrl } from './validation.js';
+
+interface NormalizedConfig {
+  readonly url: string;
+  readonly anonKey: string;
+  readonly schema: string;
+  readonly fetch: typeof fetch;
+  readonly realtime: boolean;
+  readonly realtimeClient: SupabaseDbAdapterOptions['realtimeClient'];
+}
+
+export function createSupabaseDbAdapter(options: SupabaseDbAdapterOptions): SupabaseDbAdapter {
+  const config = normalizeConfig(options);
+  const baseAdapter: DbAdapter = {
+    capabilities: {
+      supportsTransactions: false,
+      supportsReturning: true,
+      supportsRealtime: config.realtime && config.realtimeClient !== undefined,
+    },
+
+    async select<TRecord extends object = DbRecord>(
+      input: DbSelectInput,
+    ): Promise<DbResult<TRecord[]>> {
+      return requestRows<TRecord>(config, buildSelectUrl(config.url, input), {
+        method: 'GET',
+      });
+    },
+
+    async findById<TRecord extends object = DbRecord>(
+      input: DbFindByIdInput,
+    ): Promise<DbResult<TRecord | null>> {
+      const result = await requestRows<TRecord>(
+        config,
+        buildSelectUrl(config.url, {
+          table: input.table,
+          columns: input.columns,
+          filters: [{ field: 'id', operator: 'eq', value: input.id }],
+          page: { limit: 1 },
+        }),
+        { method: 'GET' },
+      );
+
+      if (!result.ok) {
+        return result;
+      }
+
+      const records = result.data ?? [];
+
+      return { ok: true, data: records[0] ?? null };
+    },
+
+    async insert<TRecord extends object = DbRecord>(
+      input: DbInsertInput<TRecord>,
+    ): Promise<DbResult<TRecord[]>> {
+      const url = buildMutationUrl(config.url, input.table, []);
+
+      return requestRows<TRecord>(config, url, {
+        method: 'POST',
+        body: JSON.stringify(input.values),
+      });
+    },
+
+    async update<TRecord extends object = DbRecord>(
+      input: DbUpdateInput<TRecord>,
+    ): Promise<DbResult<TRecord[]>> {
+      const validationError = validateRequiredFilters(input.filters, 'Update');
+
+      if (validationError !== null) {
+        return validationError;
+      }
+
+      const url = buildMutationUrl(config.url, input.table, input.filters);
+
+      return requestRows<TRecord>(config, url, {
+        method: 'PATCH',
+        body: JSON.stringify(input.values),
+      });
+    },
+
+    async delete<TRecord extends object = DbRecord>(
+      input: DbDeleteInput,
+    ): Promise<DbResult<TRecord[]>> {
+      const validationError = validateRequiredFilters(input.filters, 'Delete');
+
+      if (validationError !== null) {
+        return validationError;
+      }
+
+      const url = buildMutationUrl(config.url, input.table, input.filters);
+
+      return requestRows<TRecord>(config, url, {
+        method: 'DELETE',
+      });
+    },
+  };
+
+  if (!config.realtime || config.realtimeClient === undefined) {
+    return baseAdapter;
+  }
+
+  return {
+    ...baseAdapter,
+    realtime: createRealtimeApi({
+      client: config.realtimeClient,
+      defaultSchema: config.schema,
+    }),
+  };
+}
+
+function normalizeConfig(options: SupabaseDbAdapterOptions): NormalizedConfig {
+  const fetchImplementation = options.fetch ?? globalThis.fetch;
+
+  if (typeof fetchImplementation !== 'function') {
+    throw new TypeError('A fetch implementation is required to use Supabase Database.');
+  }
+
+  return {
+    url: validateUrl(options.url),
+    anonKey: validateKey(options.anonKey, 'Supabase anon key'),
+    schema: options.schema ?? 'public',
+    fetch: fetchImplementation,
+    realtime: options.realtime ?? false,
+    realtimeClient: options.realtimeClient,
+  };
+}
+
+async function requestRows<TRecord extends object>(
+  config: NormalizedConfig,
+  url: URL,
+  init: RequestInit,
+): Promise<DbResult<TRecord[]>> {
+  try {
+    const response = await config.fetch(url, {
+      ...init,
+      headers: createHeaders(config, init.headers),
+    });
+    const body = await readJsonBody(response);
+
+    if (!response.ok) {
+      return { ok: false, error: mapHttpError(response.status, body) };
+    }
+
+    const records = normalizeRecords<TRecord>(body);
+
+    if (records === null) {
+      return {
+        ok: false,
+        error: createDbError(
+          'provider_error',
+          'Supabase Database returned an invalid records response.',
+          body,
+        ),
+      };
+    }
+
+    return { ok: true, data: records };
+  } catch (error) {
+    if (error instanceof TypeError) {
+      return { ok: false, error: createDbError('validation_error', error.message, error) };
+    }
+
+    return { ok: false, error: mapNetworkError(error) };
+  }
+}
+
+function validateRequiredFilters(
+  filters: readonly DbFilter[],
+  label: string,
+): DbResult<never> | null {
+  try {
+    validateFilters(filters, label);
+    return null;
+  } catch (error) {
+    return {
+      ok: false,
+      error: createDbError(
+        'validation_error',
+        error instanceof Error ? error.message : `${label} filters are invalid.`,
+        error,
+      ),
+    };
+  }
+}
+
+function createHeaders(
+  config: NormalizedConfig,
+  existingHeaders: HeadersInit | undefined,
+): Headers {
+  const headers = new Headers(existingHeaders);
+
+  headers.set('apikey', config.anonKey);
+  headers.set('Authorization', `Bearer ${config.anonKey}`);
+  headers.set('Accept', 'application/json');
+  headers.set('Content-Type', 'application/json');
+  headers.set('Prefer', 'return=representation');
+
+  if (config.schema !== 'public') {
+    headers.set('Accept-Profile', config.schema);
+    headers.set('Content-Profile', config.schema);
+  }
+
+  return headers;
+}
+
+async function readJsonBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+
+  if (text.trim().length === 0) {
+    return [];
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function normalizeRecords<TRecord extends object>(value: unknown): TRecord[] | null {
+  if (Array.isArray(value)) {
+    return value.filter(isRecord<TRecord>);
+  }
+
+  if (isRecord<TRecord>(value)) {
+    return [value];
+  }
+
+  return null;
+}
+
+function isRecord<TRecord extends object>(value: unknown): value is TRecord {
+  return typeof value === 'object' && value !== null;
+}

package/src/admin.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test';
+
+import { createSupabaseDbAdminAdapter } from './admin.js';
+
+describe('createSupabaseDbAdminAdapter', () => {
+  test('generates create collection SQL without executing by default', async () => {
+    const adapter = createSupabaseDbAdminAdapter({
+      url: 'https://example.supabase.co',
+      serviceRoleKey: 'service-role',
+    });
+
+    const result = await adapter.createCollection({
+      name: 'posts',
+      fields: [
+        { name: 'title', type: 'text', required: true },
+        { name: 'like_count', type: 'number', defaultValue: 0 },
+        { name: 'published', type: 'boolean', defaultValue: false },
+      ],
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.ok ? result.executed : true).toBe(false);
+    expect(result.ok ? result.sql : '').toContain('create table if not exists "public"."posts"');
+    expect(result.ok ? result.sql : '').toContain(
+      '"id" uuid primary key default gen_random_uuid()',
+    );
+    expect(result.ok ? result.sql : '').toContain('"title" text not null');
+    expect(result.ok ? result.sql : '').toContain('"like_count" double precision default 0');
+    expect(result.ok ? result.sql : '').toContain('"published" boolean default false');
+  });
+
+  test('executes generated SQL only when explicitly configured', async () => {
+    const executedSql: string[] = [];
+    const adapter = createSupabaseDbAdminAdapter({
+      url: 'https://example.supabase.co',
+      serviceRoleKey: 'service-role',
+      execute: true,
+      executeSql: (sql) => {
+        executedSql.push(sql);
+        return Promise.resolve({ ok: true });
+      },
+    });
+
+    const result = await adapter.createCollection({
+      name: 'posts',
+      fields: [{ name: 'title', type: 'text' }],
+    });
+
+    expect(result).toEqual({
+      ok: true,
+      sql: executedSql[0],
+      executed: true,
+    });
+    expect(executedSql).toHaveLength(1);
+  });
+
+  test('refuses execution without a service role key', async () => {
+    const adapter = createSupabaseDbAdminAdapter({
+      url: 'https://example.supabase.co',
+      execute: true,
+      executeSql: () => Promise.resolve({ ok: true }),
+    });
+
+    const result = await adapter.createCollection({
+      name: 'posts',
+      fields: [{ name: 'title', type: 'text' }],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.error.code : '').toBe('missing_service_role_key');
+  });
+
+  test('generates delete collection SQL', () => {
+    const adapter = createSupabaseDbAdminAdapter({
+      url: 'https://example.supabase.co',
+      serviceRoleKey: 'service-role',
+    });
+
+    const result = adapter.generateDeleteCollectionSql({ name: 'posts' });
+
+    expect(result).toEqual({
+      ok: true,
+      sql: 'drop table if exists "public"."posts";',
+      executed: false,
+    });
+  });
+
+  test('rejects invalid collection names', () => {
+    const adapter = createSupabaseDbAdminAdapter({
+      url: 'https://example.supabase.co',
+      serviceRoleKey: 'service-role',
+    });
+
+    const result = adapter.generateCreateCollectionSql({
+      name: 'invalid-name',
+      fields: [{ name: 'title', type: 'text' }],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.ok === false ? result.error.code : '').toBe('validation_error');
+  });
+});