@an5/adapters 0.2.5 → 0.2.9

package/typescript/src/nbase/client.ts

@@ -0,0 +1,214 @@
+/**
+ * NBase — Neural Vector Database client.
+ *
+ * NBase is a vector database with HNSW/LSH/KNN indexing exposed over a REST
+ * API. an5 uses it to move similarity search out of the database process: the
+ * vectors live in NBase, the rows stay in the relational table, and the search
+ * results are hydrated from the table by the id kept in vector metadata.
+ *
+ * The client only uses the global `fetch`, so it works in Node 18+ and in the
+ * browser without pulling in a dependency.
+ */
+
+export interface NBaseVector {
+  id: string | number;
+  vector: number[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface NBaseSearchOptions {
+  /** Number of neighbours to return. */
+  k?: number;
+  /** Distance metric; NBase accepts `cosine` and `euclidean`. */
+  distanceMetric?: 'cosine' | 'euclidean';
+  /** `hnsw` uses the graph index, anything else uses the clustered path. */
+  method?: 'hnsw' | 'clustered';
+  efSearch?: number;
+  filters?: Record<string, unknown> | Array<Record<string, unknown>>;
+  includeMetadata?: boolean;
+  includeVectors?: boolean;
+  skipCache?: boolean;
+  searchTimeoutMs?: number;
+  rerank?: boolean;
+  rerankingMethod?: string;
+  rerankLambda?: number;
+  partitionIds?: string[];
+}
+
+export interface NBaseSearchResult {
+  id: string | number;
+  /** Distance from the query vector. Lower is more similar. */
+  dist: number;
+  metadata?: Record<string, unknown>;
+  vector?: number[];
+  dimension?: number;
+}
+
+export interface NBaseClientConfig {
+  /** Base URL, e.g. `http://localhost:1307`. */
+  url: string;
+  /** Optional bearer token, for deployments behind an auth proxy. */
+  token?: string;
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number;
+  /** Injectable for tests and for runtimes without a global fetch. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface NBaseStats {
+  vectorCount?: number;
+  metadataCount?: number;
+  memoryUsage?: number;
+  [key: string]: unknown;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+export class NBaseError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly body?: unknown,
+  ) {
+    super(message);
+    this.name = 'NBaseError';
+  }
+}
+
+export class NBaseVectorClient {
+  private readonly baseUrl: string;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(private readonly config: NBaseClientConfig) {
+    this.baseUrl = String(config.url).replace(/\/+$/, '');
+    const impl = config.fetchImpl ?? (globalThis as { fetch?: typeof fetch }).fetch;
+    if (!impl) {
+      throw new NBaseError('No fetch implementation available. Node 18+ or a fetch polyfill is required.');
+    }
+    this.fetchImpl = impl;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  }
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          'content-type': 'application/json',
+          ...(this.config.token ? { authorization: `Bearer ${this.config.token}` } : {}),
+          ...(init?.headers as Record<string, string> | undefined),
+        },
+      });
+
+      const text = await response.text();
+      let body: unknown;
+      try {
+        body = text ? JSON.parse(text) : undefined;
+      } catch {
+        body = text;
+      }
+
+      if (!response.ok) {
+        const message =
+          (body && typeof body === 'object' && 'error' in (body as Record<string, unknown>)
+            ? String((body as Record<string, unknown>).error)
+            : undefined) ?? `HTTP ${response.status}`;
+        throw new NBaseError(`NBase request ${path} failed: ${message}`, response.status, body);
+      }
+      return body as T;
+    } catch (err) {
+      if (err instanceof NBaseError) throw err;
+      if ((err as { name?: string })?.name === 'AbortError') {
+        throw new NBaseError(`NBase request ${path} timed out after ${this.timeoutMs}ms`);
+      }
+      throw new NBaseError(
+        `Could not reach NBase at ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Liveness probe. NBase mounts its status routes at the server root. */
+  async health(): Promise<{ status: string; version?: string }> {
+    return this.request<{ status: string; version?: string }>('/health');
+  }
+
+  /** Vector count, memory use and other database statistics. */
+  async stats(): Promise<NBaseStats> {
+    return this.request<NBaseStats>('/stats');
+  }
+
+  /** Adds or replaces vectors. NBase accepts a single vector or a bulk array. */
+  async addVectors(vectors: NBaseVector[]): Promise<{ count: number; ids?: Array<string | number> }> {
+    if (vectors.length === 0) return { count: 0 };
+    const result = await this.request<{ count: number; addedIds?: Array<string | number> }>(
+      '/api/vectors',
+      { method: 'POST', body: JSON.stringify({ vectors: vectors.length === 1 ? vectors[0] : vectors }) },
+    );
+    return { count: result.count ?? vectors.length, ...(result.addedIds ? { ids: result.addedIds } : {}) };
+  }
+
+  /** Nearest-neighbour search. Results are ordered by ascending `dist`. */
+  async search(vector: number[], options: NBaseSearchOptions = {}): Promise<NBaseSearchResult[]> {
+    const body = await this.request<{ results?: NBaseSearchResult[] }>('/api/search', {
+      method: 'POST',
+      body: JSON.stringify({
+        query: vector,
+        k: options.k ?? 10,
+        ...(options.distanceMetric ? { distanceMetric: options.distanceMetric } : {}),
+        ...(options.method ? { method: options.method } : {}),
+        ...(options.efSearch !== undefined ? { efSearch: options.efSearch } : {}),
+        ...(options.filters ? { filters: options.filters } : {}),
+        ...(options.includeMetadata !== undefined ? { includeMetadata: options.includeMetadata } : {}),
+        ...(options.includeVectors !== undefined ? { includeVectors: options.includeVectors } : {}),
+        ...(options.skipCache !== undefined ? { skipCache: options.skipCache } : {}),
+        ...(options.searchTimeoutMs !== undefined ? { searchTimeoutMs: options.searchTimeoutMs } : {}),
+        ...(options.rerank !== undefined ? { rerank: options.rerank } : {}),
+        ...(options.rerankingMethod ? { rerankingMethod: options.rerankingMethod } : {}),
+        ...(options.rerankLambda !== undefined ? { rerankLambda: options.rerankLambda } : {}),
+        ...(options.partitionIds ? { partitionIds: options.partitionIds } : {}),
+      }),
+    });
+    return body.results ?? [];
+  }
+
+  /** Reads a single vector. Returns undefined when the id is unknown. */
+  async get(id: string | number): Promise<NBaseSearchResult | undefined> {
+    try {
+      return await this.request<NBaseSearchResult>(`/api/vectors/${encodeURIComponent(String(id))}`);
+    } catch (err) {
+      if (err instanceof NBaseError && err.status === 404) return undefined;
+      throw err;
+    }
+  }
+
+  async exists(id: string | number): Promise<boolean> {
+    const result = await this.request<{ exists?: boolean }>(
+      `/api/vectors/${encodeURIComponent(String(id))}/exists`,
+    );
+    return result.exists === true;
+  }
+
+  async delete(id: string | number): Promise<boolean> {
+    await this.request(`/api/vectors/${encodeURIComponent(String(id))}`, { method: 'DELETE' });
+    return true;
+  }
+
+  async updateMetadata(id: string | number, metadata: Record<string, unknown>): Promise<boolean> {
+    await this.request(`/api/vectors/${encodeURIComponent(String(id))}/metadata`, {
+      method: 'PATCH',
+      body: JSON.stringify(metadata),
+    });
+    return true;
+  }
+}
+
+/** Creates an NBase vector client. */
+export function createNBaseVectorClient(config: NBaseClientConfig): NBaseVectorClient {
+  return new NBaseVectorClient(config);
+}

package/typescript/src/nbase/index.ts

@@ -0,0 +1,104 @@
+/**
+ * NBase connection-string and adapter configuration.
+ *
+ * NBase is configured through the connection string alone:
+ *
+ *    createAn5Adapter({ connectionString: 'nbase://localhost:1307' })
+ *
+ * Accepted forms are `nbase://host:port`, `nbase:host:port` and an explicit
+ * scheme, with optional `?token=…&timeoutMs=…&method=…` options. An adapter
+ * created this way is vector-only: it has no relational database, so a search
+ * returns the NBase hits instead of table rows.
+ */
+import {
+  NBaseVectorClient,
+  NBaseError,
+  createNBaseVectorClient,
+  type NBaseClientConfig,
+  type NBaseVector,
+  type NBaseSearchOptions,
+  type NBaseSearchResult,
+  type NBaseStats,
+} from './client';
+
+export interface NBaseAdapterConfig extends NBaseClientConfig {
+  url: string;
+  /**
+   * Metadata key that holds the relational row id. `an5Id` by default, which
+   * is what `indexTableVectors` writes.
+   */
+  idField?: string;
+  /** Metadata key holding the model name, used to keep collections apart. */
+  modelField?: string;
+  /** Force the search method instead of letting NBase choose. */
+  method?: 'hnsw' | 'clustered';
+}
+
+/** Matches `nbase:`, `nbase://` and `nbase=http(s)://` at the start of a value. */
+const NBASE_PREFIX = /^nbase:(?:\/\/)?/i;
+
+/** True when the whole connection string points at NBase. */
+export function isNBaseConnectionString(connectionString: string): boolean {
+  return NBASE_PREFIX.test(connectionString.trim());
+}
+
+/** Builds options from a URL and an optional query string. */
+function buildOptions(url: string, query?: string): NBaseAdapterConfig {
+  const params = new URLSearchParams(query ?? '');
+  const trimmed = url.trim().replace(/\/+$/, '');
+  // `nbase://host:port` is shorthand for the same host over HTTP; an explicit
+  // scheme is used as-is so https deployments work.
+  const withScheme = !trimmed
+    ? 'http://localhost:1307'
+    : /^[a-z]+:\/\//i.test(trimmed)
+      ? trimmed
+      : `http://${trimmed}`;
+  return {
+    url: withScheme,
+    ...(params.get('token') ? { token: params.get('token') as string } : {}),
+    ...(params.get('timeoutMs') ? { timeoutMs: Number(params.get('timeoutMs')) } : {}),
+    ...(params.get('idField') ? { idField: params.get('idField') as string } : {}),
+    ...(params.get('modelField') ? { modelField: params.get('modelField') as string } : {}),
+    ...(params.get('method') ? { method: params.get('method') as 'hnsw' | 'clustered' } : {}),
+  };
+}
+
+/**
+ * Parses an NBase connection string.
+ *
+ * Accepts `nbase:http://host:port`, `nbase://host:port` and
+ * `nbase:host:port`, with optional `?token=…&timeoutMs=…` options.
+ */
+export function parseNBaseConnectionString(connectionString: string): NBaseAdapterConfig {
+  const raw = connectionString.trim();
+  if (!isNBaseConnectionString(raw)) {
+    throw new Error(`Not an NBase connection string: ${raw}`);
+  }
+
+  const [url, query] = raw.replace(NBASE_PREFIX, '').split('?');
+  return buildOptions(url ?? '', query);
+}
+
+/** Builds the vector id used to link a NBase vector back to a relational row. */
+export function buildVectorId(model: string, id: string | number): string {
+  return `${model}:${id}`;
+}
+
+/** Splits a vector id produced by {@link buildVectorId}. */
+export function parseVectorId(vectorId: string | number): { model: string; id: string } {
+  const raw = String(vectorId);
+  const separator = raw.indexOf(':');
+  if (separator === -1) return { model: '', id: raw };
+  return { model: raw.slice(0, separator), id: raw.slice(separator + 1) };
+}
+
+export function createNBaseClient(config: NBaseAdapterConfig | string): {
+  client: NBaseVectorClient;
+  options: NBaseAdapterConfig;
+} {
+  const options: NBaseAdapterConfig = typeof config === 'string' ? parseNBaseConnectionString(config) : config;
+  return { client: createNBaseVectorClient(options), options };
+}
+
+export { NBaseVectorClient, NBaseError, createNBaseVectorClient };
+export type { NBaseClientConfig, NBaseVector, NBaseSearchOptions, NBaseSearchResult, NBaseStats };

package/typescript/src/postgres/engine.ts

@@ -1,87 +1,87 @@
-import type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from '../base/types';
-
-// ─── PostgreSQL Engine ─────────────────────────────────────────────────────────────
-
-let PgPool: any = null;
-try { PgPool = require('pg').Pool; } catch { }
-
-export class PostgresEngine implements QueryEngine {
-  dialect: Dialect = 'postgres';
-  private pool: any = null;
-
-  constructor(adapterConfig: An5AdapterConfig) {
-    if (!PgPool) throw new Error('pg package is required for PostgreSQL support. Run: npm install pg');
-    this.pool = new PgPool({
-      connectionString: adapterConfig.connectionString,
-      max: adapterConfig.poolMax ?? 10,
-    });
-  }
-
-  /** Convert @name → $N; identical names reuse the same $N */
-  private transform(query: string, params?: Record<string, any>): { text: string; values: any[] } {
-    if (!params || Object.keys(params).length === 0) return { text: query, values: [] };
-    const values: any[] = [];
-    const seen: Record<string, number> = {};
-    const text = query.replace(/@(\w+)/g, (_, name: string) => {
-      if (seen[name] !== undefined) return `$${seen[name]}`;
-      const idx = values.length + 1;
-      seen[name] = idx;
-      values.push(params[name] ?? null);
-      return `$${idx}`;
-    });
-    return { text, values };
-  }
-
-  async exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> {
-    const { text, values } = this.transform(query, params);
-    const result = await this.pool.query(text, values);
-    return result.rows as T[];
-  }
-
-  async executeRaw(query: string, params?: Record<string, any>): Promise<number> {
-    const { text, values } = this.transform(query, params);
-    const result = await this.pool.query(text, values);
-    return result.rowCount ?? 0;
-  }
-
-  async connect(): Promise<void> {
-    const client = await this.pool.connect();
-    client.release();
-  }
-
-  async disconnect(): Promise<void> { await this.pool.end(); }
-
-  async beginTransaction(): Promise<TransactionHandle> {
-    const client = await this.pool.connect();
-    await client.query('BEGIN');
-
-    const transform = (query: string, params?: Record<string, any>) => {
-      if (!params || Object.keys(params).length === 0) return { text: query, values: [] };
-      const values: any[] = [];
-      const seen: Record<string, number> = {};
-      const text = query.replace(/@(\w+)/g, (_, name: string) => {
-        if (seen[name] !== undefined) return `$${seen[name]}`;
-        const idx = values.length + 1;
-        seen[name] = idx;
-        values.push(params[name] ?? null);
-        return `$${idx}`;
-      });
-      return { text, values };
-    };
-
-    return {
-      exec: async <T>(q: string, p?: Record<string, any>) => {
-        const { text, values } = transform(q, p);
-        const r = await client.query(text, values);
-        return (r.rows || []) as T[];
-      },
-      executeRaw: async (q: string, p?: Record<string, any>) => {
-        const { text, values } = transform(q, p);
-        const r = await client.query(text, values);
-        return r.rowCount ?? 0;
-      },
-      commit: async () => { await client.query('COMMIT'); client.release(); },
-      rollback: async () => { await client.query('ROLLBACK'); client.release(); },
-    };
-  }
-}
+import type { An5AdapterConfig, Dialect, QueryEngine, TransactionHandle } from '../base/types';
+
+// ─── PostgreSQL Engine ─────────────────────────────────────────────────────────────
+
+let PgPool: any = null;
+try { PgPool = require('pg').Pool; } catch { }
+
+export class PostgresEngine implements QueryEngine {
+  dialect: Dialect = 'postgres';
+  private pool: any = null;
+
+  constructor(adapterConfig: An5AdapterConfig) {
+    if (!PgPool) throw new Error('pg package is required for PostgreSQL support. Run: npm install pg');
+    this.pool = new PgPool({
+      connectionString: adapterConfig.connectionString ?? '',
+      max: adapterConfig.poolMax ?? 10,
+    });
+  }
+
+  /** Convert @name → $N; identical names reuse the same $N */
+  private transform(query: string, params?: Record<string, any>): { text: string; values: any[] } {
+    if (!params || Object.keys(params).length === 0) return { text: query, values: [] };
+    const values: any[] = [];
+    const seen: Record<string, number> = {};
+    const text = query.replace(/@(\w+)/g, (_, name: string) => {
+      if (seen[name] !== undefined) return `$${seen[name]}`;
+      const idx = values.length + 1;
+      seen[name] = idx;
+      values.push(params[name] ?? null);
+      return `$${idx}`;
+    });
+    return { text, values };
+  }
+
+  async exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> {
+    const { text, values } = this.transform(query, params);
+    const result = await this.pool.query(text, values);
+    return result.rows as T[];
+  }
+
+  async executeRaw(query: string, params?: Record<string, any>): Promise<number> {
+    const { text, values } = this.transform(query, params);
+    const result = await this.pool.query(text, values);
+    return result.rowCount ?? 0;
+  }
+
+  async connect(): Promise<void> {
+    const client = await this.pool.connect();
+    client.release();
+  }
+
+  async disconnect(): Promise<void> { await this.pool.end(); }
+
+  async beginTransaction(): Promise<TransactionHandle> {
+    const client = await this.pool.connect();
+    await client.query('BEGIN');
+
+    const transform = (query: string, params?: Record<string, any>) => {
+      if (!params || Object.keys(params).length === 0) return { text: query, values: [] };
+      const values: any[] = [];
+      const seen: Record<string, number> = {};
+      const text = query.replace(/@(\w+)/g, (_, name: string) => {
+        if (seen[name] !== undefined) return `$${seen[name]}`;
+        const idx = values.length + 1;
+        seen[name] = idx;
+        values.push(params[name] ?? null);
+        return `$${idx}`;
+      });
+      return { text, values };
+    };
+
+    return {
+      exec: async <T>(q: string, p?: Record<string, any>) => {
+        const { text, values } = transform(q, p);
+        const r = await client.query(text, values);
+        return (r.rows || []) as T[];
+      },
+      executeRaw: async (q: string, p?: Record<string, any>) => {
+        const { text, values } = transform(q, p);
+        const r = await client.query(text, values);
+        return r.rowCount ?? 0;
+      },
+      commit: async () => { await client.query('COMMIT'); client.release(); },
+      rollback: async () => { await client.query('ROLLBACK'); client.release(); },
+    };
+  }
+}

package/typescript/src/postgres/index.ts

@@ -1 +1 @@
-export * from './engine';
+export * from './engine';

package/typescript/src/sqlite/browserEngine.ts

@@ -0,0 +1,192 @@
+import type { Dialect, QueryEngine, TransactionHandle } from '../base/types';
+
+// ─── Browser SQLite Driver & Config ──────────────────────────────────────────────────
+
+export interface SqliteDriver {
+  exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> | T[];
+  executeRaw?(query: string, params?: Record<string, any>): Promise<number> | number;
+  close?(): Promise<void> | void;
+}
+
+export interface SqliteBrowserConfig {
+  db?: any; // sql.js Database instance or SQLite WASM DB
+  driver?: SqliteDriver;
+  exec?: <T = any>(query: string, params?: Record<string, any>) => Promise<T[]> | T[];
+  executeRaw?: (query: string, params?: Record<string, any>) => Promise<number> | number;
+}
+
+// ─── Browser SQLite Engine ──────────────────────────────────────────────────────────
+
+export class SqliteBrowserEngine implements QueryEngine {
+  dialect: Dialect = 'sqlite';
+  private db: any = null;
+  private driver: SqliteDriver | null = null;
+  private customExec: ((query: string, params?: Record<string, any>) => Promise<any[]> | any[]) | null = null;
+  private customExecuteRaw: ((query: string, params?: Record<string, any>) => Promise<number> | number) | null = null;
+
+  constructor(config?: SqliteBrowserConfig | any) {
+    if (!config) return;
+
+    if (config.exec && typeof config.exec === 'function') {
+      this.customExec = config.exec;
+      this.customExecuteRaw = config.executeRaw ?? null;
+      return;
+    }
+
+    if (config.driver) {
+      this.driver = config.driver;
+      return;
+    }
+
+    // Direct DB instance (e.g. sql.js Database or sqlite-wasm)
+    if (config.db) {
+      this.db = config.db;
+      return;
+    }
+
+    // If config itself looks like a driver with exec()
+    if (typeof config.exec === 'function' && typeof config.run !== 'function' && typeof config.prepare !== 'function') {
+      this.driver = config as SqliteDriver;
+      return;
+    }
+
+    // If config itself is a Database instance (has prepare, exec, run)
+    if (typeof config.prepare === 'function' || typeof config.run === 'function' || typeof config.exec === 'function') {
+      this.db = config;
+    }
+  }
+
+  private normalizeSqlJsParams(params?: Record<string, any>): Record<string, any> {
+    if (!params || typeof params !== 'object') return {};
+    const normalized: Record<string, any> = {};
+    for (const [k, v] of Object.entries(params)) {
+      const key = k.startsWith('@') || k.startsWith(':') || k.startsWith('$') ? k : `@${k}`;
+      normalized[key] = v;
+    }
+    return normalized;
+  }
+
+  async exec<T = any>(query: string, params?: Record<string, any>): Promise<T[]> {
+    if (this.customExec) {
+      return await this.customExec(query, params);
+    }
+
+    if (this.driver) {
+      return await this.driver.exec<T>(query, params);
+    }
+
+    if (this.db) {
+      // sql.js Database with prepare()
+      if (typeof this.db.prepare === 'function') {
+        const stmt = this.db.prepare(query);
+        try {
+          if (params && Object.keys(params).length > 0) {
+            stmt.bind(this.normalizeSqlJsParams(params));
+          }
+          const results: T[] = [];
+          while (stmt.step()) {
+            results.push(stmt.getAsObject() as T);
+          }
+          return results;
+        } finally {
+          stmt.free();
+        }
+      }
+
+      // Fallback sql.js db.exec()
+      if (typeof this.db.exec === 'function') {
+        const res = this.db.exec(query);
+        if (!res || res.length === 0) return [];
+        const { columns, values } = res[0];
+        return values.map((row: any[]) => {
+          const obj: any = {};
+          columns.forEach((col: string, i: number) => {
+            obj[col] = row[i];
+          });
+          return obj as T;
+        });
+      }
+    }
+
+    throw new Error('SqliteBrowserEngine: No SQLite database or driver provided. Pass a sql.js db instance or custom driver.');
+  }
+
+  async executeRaw(query: string, params?: Record<string, any>): Promise<number> {
+    if (this.customExecuteRaw) {
+      return await this.customExecuteRaw(query, params);
+    }
+
+    if (this.driver && typeof this.driver.executeRaw === 'function') {
+      return await this.driver.executeRaw(query, params);
+    }
+
+    if (this.db) {
+      if (typeof this.db.prepare === 'function') {
+        const stmt = this.db.prepare(query);
+        try {
+          if (params && Object.keys(params).length > 0) {
+            stmt.bind(this.normalizeSqlJsParams(params));
+          }
+          stmt.step();
+          if (typeof this.db.getRowsModified === 'function') {
+            return this.db.getRowsModified();
+          }
+          return 1;
+        } finally {
+          stmt.free();
+        }
+      }
+
+      if (typeof this.db.run === 'function') {
+        this.db.run(query, this.normalizeSqlJsParams(params));
+        if (typeof this.db.getRowsModified === 'function') {
+          return this.db.getRowsModified();
+        }
+        return 1;
+      }
+    }
+
+    const rows = await this.exec(query, params);
+    return rows.length;
+  }
+
+  async connect(): Promise<void> {}
+
+  async disconnect(): Promise<void> {
+    if (this.driver && typeof this.driver.close === 'function') {
+      await this.driver.close();
+    } else if (this.db && typeof this.db.close === 'function') {
+      this.db.close();
+    }
+  }
+
+  async beginTransaction(): Promise<TransactionHandle> {
+    await this.executeRaw('BEGIN');
+    let done = false;
+
+    return {
+      exec: async <T>(q: string, p?: Record<string, any>) => this.exec<T>(q, p),
+      executeRaw: async (q: string, p?: Record<string, any>) => this.executeRaw(q, p),
+      commit: async () => {
+        if (!done) {
+          await this.executeRaw('COMMIT');
+          done = true;
+        }
+      },
+      rollback: async () => {
+        if (!done) {
+          await this.executeRaw('ROLLBACK');
+          done = true;
+        }
+      },
+    };
+  }
+}
+
+// ─── Browser SQLite Adapter Factory ──────────────────────────────────────────────────
+
+export function createBrowserSqliteAdapter(config: SqliteBrowserConfig | any): any {
+  const { An5Adapter } = require('../an5Adapter');
+  return new An5Adapter({ engine: new SqliteBrowserEngine(config) });
+}
+