@lota-sdk/core 0.1.5

package/src/db/service.ts

@@ -0,0 +1,932 @@
+import {
+  BoundQuery,
+  RecordId,
+  ServerError,
+  StringRecordId,
+  Surreal,
+  Table,
+  and,
+  createRemoteEngines,
+  eq,
+} from 'surrealdb'
+import type { ExprLike, Mutation, SurrealTransaction, Values } from 'surrealdb'
+import type { z } from 'zod'
+
+import type { RecordIdInput } from './record-id'
+import { ensureRecordId, readCustomStringValue } from './record-id'
+import type { DatabaseTable } from './tables'
+
+export class SurrealDBError extends Error {
+  constructor(
+    message: string,
+    public readonly query?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+    this.name = 'SurrealDBError'
+  }
+}
+
+export interface SurrealDatabaseConfig {
+  url: string
+  namespace: string
+  database: string
+  username?: string
+  password?: string
+}
+
+export interface SurrealDatabaseLogger {
+  info?: (message: string) => void
+  warn?: (message: string) => void
+  error?: (message: string) => void
+}
+
+export type BoundQueryLike = { query: string; bindings?: Record<string, unknown> }
+
+interface FindManyOptions {
+  limit?: number
+  offset?: number
+  orderBy?: string
+  orderDir?: 'ASC' | 'DESC'
+}
+
+type MutationBuilder = {
+  content: (data: Record<string, unknown>) => MutationBuilder
+  replace: (data: Record<string, unknown>) => MutationBuilder
+  patch: (data: Record<string, unknown>) => MutationBuilder
+  merge: (data: Record<string, unknown>) => MutationBuilder
+  output: (mode: 'after' | 'before') => Promise<unknown>
+}
+
+export type CreateMutationBuilder = {
+  content: (data: Record<string, unknown>) => CreateMutationBuilder
+  output: (mode: 'after' | 'before') => Promise<unknown>
+}
+
+export interface DatabaseTransaction {
+  query: (query: unknown) => Promise<unknown>
+  create: (target: unknown) => CreateMutationBuilder
+  relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) => Promise<unknown>
+  commit: () => Promise<void>
+  cancel: () => Promise<void>
+}
+
+function configureMutation(
+  builder: MutationBuilder,
+  mutation: Mutation,
+  data: Record<string, unknown>,
+): MutationBuilder {
+  if (mutation === 'content') {
+    return builder.content(data)
+  }
+  if (mutation === 'replace') {
+    return builder.replace(data)
+  }
+  if (mutation === 'patch') {
+    return builder.patch(data)
+  }
+  return builder.merge(data)
+}
+
+function isRecordValue(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isBoundQueryLike(value: unknown): value is BoundQueryLike {
+  if (!isRecordValue(value)) {
+    return false
+  }
+
+  if (typeof value.query !== 'string') {
+    return false
+  }
+
+  return value.bindings === undefined || isRecordValue(value.bindings)
+}
+
+function toStringLikeValue(value: unknown): string | null {
+  if (!value || typeof value !== 'object') {
+    return null
+  }
+
+  const stringValue = readCustomStringValue(value)
+  if (typeof stringValue !== 'string' || stringValue.length === 0 || stringValue === '[object Object]') {
+    return null
+  }
+
+  return stringValue
+}
+
+const CONNECT_MAX_ATTEMPTS = 5
+const CONNECT_RETRY_BASE_DELAY_MS = 100
+const CONNECT_RETRY_JITTER_MS = 50
+const CONNECT_ATTEMPT_TIMEOUT_MS = 5_000
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined
+
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<T>((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(message)), timeoutMs)
+      }),
+    ])
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId)
+    }
+  }
+}
+
+export class SurrealDBService {
+  private client: Surreal | null = null
+  private isConnected = false
+  private connectPromise: Promise<void> | null = null
+
+  constructor(
+    private readonly config: SurrealDatabaseConfig,
+    private readonly logger?: SurrealDatabaseLogger,
+  ) {}
+
+  private toSurrealError(error: unknown, query?: string): never {
+    if (error instanceof SurrealDBError) {
+      throw error
+    }
+
+    if (error instanceof ServerError) {
+      throw new SurrealDBError(`${error.name}: ${error.message}`, query, { cause: error })
+    }
+
+    if (error instanceof Error) {
+      throw new SurrealDBError(error.message, query, { cause: error })
+    }
+
+    throw new SurrealDBError(String(error), query)
+  }
+
+  private isEmbeddedEngine(url: string) {
+    return (
+      url === 'mem://' ||
+      url.startsWith('mem://') ||
+      url.startsWith('surrealkv://') ||
+      url.startsWith('surrealkv+versioned://') ||
+      url.startsWith('indxdb://')
+    )
+  }
+
+  private async getOrCreateClient(): Promise<Surreal> {
+    if (this.client) {
+      return this.client
+    }
+
+    const codecOptions = { useNativeDates: true }
+
+    if (this.isEmbeddedEngine(this.config.url)) {
+      const { createNodeEngines } = await import('@surrealdb/node')
+      this.client = new Surreal({
+        engines: { ...createRemoteEngines(), ...createNodeEngines() } as NonNullable<
+          ConstructorParameters<typeof Surreal>[0]
+        >['engines'],
+        codecOptions,
+      })
+      return this.client
+    }
+
+    this.client = new Surreal({ engines: createRemoteEngines(), codecOptions })
+    return this.client
+  }
+
+  private async resetClient(): Promise<void> {
+    if (!this.client) {
+      return
+    }
+
+    try {
+      await this.client.close()
+    } catch {
+    } finally {
+      this.client = null
+    }
+  }
+
+  private isRetriableConnectConflict(error: unknown): boolean {
+    if (!(error instanceof Error)) {
+      return false
+    }
+
+    const message = error.message.toLowerCase()
+    return (
+      message.includes('transaction conflict') ||
+      message.includes('transaction read conflict') ||
+      message.includes('read or write conflict') ||
+      message.includes('write conflict') ||
+      message.includes('resource busy') ||
+      message.includes('this transaction can be retried')
+    )
+  }
+
+  async connect(): Promise<void> {
+    if (this.isConnected) {
+      return
+    }
+
+    if (this.connectPromise) {
+      await this.connectPromise
+      return
+    }
+
+    this.connectPromise = (async () => {
+      let lastError: unknown = null
+
+      for (let attempt = 1; attempt <= CONNECT_MAX_ATTEMPTS; attempt += 1) {
+        try {
+          const client = await this.getOrCreateClient()
+
+          await withTimeout(
+            client.connect(this.config.url, {
+              namespace: this.config.namespace,
+              database: this.config.database,
+              authentication: this.isEmbeddedEngine(this.config.url)
+                ? undefined
+                : { username: this.config.username ?? '', password: this.config.password ?? '' },
+            }),
+            CONNECT_ATTEMPT_TIMEOUT_MS,
+            `Timed out connecting to SurrealDB at ${this.config.url}`,
+          )
+
+          this.isConnected = true
+          this.logger?.info?.('Connected to SurrealDB')
+          return
+        } catch (error) {
+          lastError = error
+          this.isConnected = false
+          await this.resetClient()
+
+          const retriable = this.isRetriableConnectConflict(error)
+          const hasMoreAttempts = attempt < CONNECT_MAX_ATTEMPTS
+          if (!retriable || !hasMoreAttempts) {
+            break
+          }
+
+          const backoffMs =
+            CONNECT_RETRY_BASE_DELAY_MS * 2 ** (attempt - 1) + Math.floor(Math.random() * CONNECT_RETRY_JITTER_MS)
+          this.logger?.warn?.(
+            `Retrying SurrealDB connect after retryable transaction conflict (${attempt + 1}/${CONNECT_MAX_ATTEMPTS})`,
+          )
+          await Bun.sleep(backoffMs)
+        }
+      }
+
+      this.toSurrealError(lastError)
+    })()
+
+    try {
+      await this.connectPromise
+    } finally {
+      this.connectPromise = null
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.connectPromise) {
+      try {
+        await this.connectPromise
+      } catch (error) {
+        this.logger?.warn?.(
+          `Disconnect observed failed in-flight connect: ${error instanceof Error ? error.message : String(error)}`,
+        )
+        return
+      }
+    }
+
+    if (!this.isConnected) {
+      return
+    }
+
+    this.isConnected = false
+
+    try {
+      await this.client?.close()
+    } finally {
+      this.client = null
+    }
+  }
+
+  private async ensureConnected(): Promise<Surreal> {
+    if (this.connectPromise) {
+      await this.connectPromise
+    }
+
+    if (this.client === null) {
+      throw new SurrealDBError('Database not connected')
+    }
+
+    return this.client
+  }
+
+  private normalizeRecordId(id: unknown, table: DatabaseTable): ReturnType<typeof ensureRecordId> {
+    try {
+      return ensureRecordId(id as RecordIdInput, table)
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new SurrealDBError(`Invalid record id for table "${table}": ${error.message}`, undefined, {
+          cause: error,
+        })
+      }
+      throw new SurrealDBError(`Invalid record id for table "${table}"`)
+    }
+  }
+
+  private normalizeQueryRows<T>(statement: unknown, schema?: z.ZodType<T>): T[] {
+    if (Array.isArray(statement)) {
+      return schema ? statement.map((row) => schema.parse(row)) : (statement as T[])
+    }
+    if (statement === null || statement === undefined) {
+      return []
+    }
+    return schema ? [schema.parse(statement)] : [statement as T]
+  }
+
+  private buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
+    const entries = Object.entries(filter)
+    if (entries.length === 0) {
+      return undefined
+    }
+
+    const expressions = entries.map(([key, value]) => eq(key, this.normalizeRuntimeValue(value)))
+    if (expressions.length === 1) {
+      return expressions[0]
+    }
+
+    return and(...expressions)
+  }
+
+  private normalizeBoundQuery(query: BoundQuery | BoundQueryLike): BoundQuery {
+    if (!(query instanceof BoundQuery) && !isBoundQueryLike(query)) {
+      throw new SurrealDBError('Invalid query object: expected a BoundQuery-like value')
+    }
+
+    return new BoundQuery(query.query, this.normalizeBindings(query.bindings))
+  }
+
+  private isSerializedRecordId(value: string): boolean {
+    return /^[a-zA-Z][a-zA-Z0-9_]*:(?:⟨.+⟩|.+)$/.test(value)
+  }
+
+  private normalizeRuntimeValue(value: unknown): unknown {
+    if (value === null || value === undefined) {
+      return value
+    }
+
+    if (
+      value instanceof Date ||
+      value instanceof RecordId ||
+      value instanceof StringRecordId ||
+      value instanceof Table
+    ) {
+      return value
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((entry) => this.normalizeRuntimeValue(entry))
+    }
+
+    if (!isRecordValue(value)) {
+      return value
+    }
+
+    if ('tb' in value && 'id' in value) {
+      return ensureRecordId(value as RecordIdInput)
+    }
+
+    const stringValue = toStringLikeValue(value)
+    if (stringValue && this.isSerializedRecordId(stringValue)) {
+      return ensureRecordId(stringValue)
+    }
+
+    const entries = Object.entries(value)
+    if (entries.length === 0) {
+      return value
+    }
+
+    return Object.fromEntries(entries.map(([key, entryValue]) => [key, this.normalizeRuntimeValue(entryValue)]))
+  }
+
+  private normalizeBindings(bindings?: Record<string, unknown>): Record<string, unknown> | undefined {
+    if (!bindings) {
+      return undefined
+    }
+
+    return this.normalizeRuntimeValue(bindings) as Record<string, unknown>
+  }
+
+  private normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
+    const normalized = this.normalizeRuntimeValue(data) as Record<string, unknown>
+    return this.stripNullValues(normalized)
+  }
+
+  /**
+   * SurrealDB v3 `option<T>` fields expect `NONE` (key omitted), not `null`.
+   * Strip top-level `null` values so they are omitted from the serialized payload,
+   * which the driver interprets as NONE.
+   */
+  private stripNullValues(data: Record<string, unknown>): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(data)) {
+      if (value !== null) {
+        result[key] = value
+      }
+    }
+    return result
+  }
+
+  private normalizeTableValue(value: unknown): Table {
+    if (value instanceof Table) {
+      return value as Table<string>
+    }
+
+    if (typeof value === 'string' && value.length > 0) {
+      return new Table(value)
+    }
+
+    const stringValue = toStringLikeValue(value)
+    if (stringValue) {
+      return new Table(stringValue)
+    }
+
+    throw new SurrealDBError('Invalid table value')
+  }
+
+  private wrapMutationBuilder(builder: MutationBuilder): MutationBuilder {
+    return {
+      content: (data) => this.wrapMutationBuilder(builder.content(this.normalizeMutationData(data))),
+      replace: (data) => this.wrapMutationBuilder(builder.replace(this.normalizeMutationData(data))),
+      patch: (data) => this.wrapMutationBuilder(builder.patch(this.normalizeMutationData(data))),
+      merge: (data) => this.wrapMutationBuilder(builder.merge(this.normalizeMutationData(data))),
+      output: (mode) => builder.output(mode),
+    }
+  }
+
+  private wrapCreateBuilder(builder: CreateMutationBuilder): CreateMutationBuilder {
+    return {
+      content: (data) => this.wrapCreateBuilder(builder.content(this.normalizeMutationData(data))),
+      output: (mode) => builder.output(mode),
+    }
+  }
+
+  private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
+    return {
+      query: (query: unknown) => tx.query(this.normalizeBoundQuery(query as BoundQuery | BoundQueryLike)),
+      create: (target: unknown) =>
+        this.wrapCreateBuilder(tx.create(this.normalizeTableValue(target)) as unknown as CreateMutationBuilder),
+      relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
+        tx.relate(
+          ensureRecordId(from as RecordIdInput),
+          this.normalizeTableValue(edgeTable),
+          ensureRecordId(to as RecordIdInput),
+          data
+            ? (this.normalizeMutationData(data as Record<string, unknown>) as Values<Record<string, unknown>>)
+            : undefined,
+        ),
+      commit: () => tx.commit(),
+      cancel: () => tx.cancel(),
+    }
+  }
+
+  private resolveQueryText(query: BoundQuery | BoundQueryLike): string {
+    return query.query
+  }
+
+  async query<T>(query: BoundQuery | BoundQueryLike): Promise<T[]> {
+    const statements = await this.queryAll<T>(query)
+    return statements.at(0) ?? []
+  }
+
+  async queryAll<T>(query: BoundQuery | BoundQueryLike, schema?: z.ZodType<T>): Promise<T[][]> {
+    const client = await this.ensureConnected()
+    const boundQuery = this.normalizeBoundQuery(query)
+    const queryText = this.resolveQueryText(boundQuery)
+
+    try {
+      const responses = await client.query(boundQuery).responses()
+
+      return responses.map((response, index) => {
+        if (!response.success) {
+          const failure = response.error
+          throw new SurrealDBError(`Statement ${index + 1}: ${failure.message}`, queryText, { cause: failure })
+        }
+        return this.normalizeQueryRows<T>(response.result, schema)
+      })
+    } catch (error) {
+      this.toSurrealError(error, queryText)
+    }
+  }
+
+  async queryOne<T extends z.ZodType>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T> | null> {
+    const results = await this.query<unknown>(query)
+    const first = results.at(0)
+    return first ? schema.parse(first) : null
+  }
+
+  async queryMany<T extends z.ZodType>(query: BoundQuery | BoundQueryLike, schema: T): Promise<z.infer<T>[]> {
+    const results = await this.query<unknown>(query)
+    return results.map((row) => schema.parse(row))
+  }
+
+  private async runSqlFile(file: Bun.BunFile): Promise<void> {
+    const sql = (await file.text()).trim()
+    if (!sql) {
+      return
+    }
+
+    await this.queryAll<unknown>(new BoundQuery(sql))
+  }
+
+  async applySchemaAndMigrations(schemaFiles: readonly Bun.BunFile[]): Promise<void> {
+    for (const schemaFile of schemaFiles) {
+      await this.runSqlFile(schemaFile)
+    }
+  }
+
+  async findOne<T extends z.ZodType>(
+    table: DatabaseTable,
+    filter: Record<string, unknown>,
+    schema: T,
+  ): Promise<z.infer<T> | null> {
+    const client = await this.ensureConnected()
+    const selection = this.buildFilterExpression(filter)
+
+    try {
+      let query = client.select<unknown>(new Table(table))
+      if (selection) {
+        query = query.where(selection)
+      }
+
+      const rows = await query.limit(1)
+      const first = rows.at(0)
+      return first ? schema.parse(first) : null
+    } catch (error) {
+      this.toSurrealError(error, `SELECT * FROM ${table} LIMIT 1`)
+    }
+  }
+
+  async findMany<T extends z.ZodType>(
+    table: DatabaseTable,
+    filter: Record<string, unknown>,
+    schema: T,
+    options?: FindManyOptions,
+  ): Promise<z.infer<T>[]> {
+    const filterKeys = Object.keys(filter)
+
+    const client = await this.ensureConnected()
+    const selection = this.buildFilterExpression(filter)
+    const orderBy = options?.orderBy
+
+    if (options && orderBy) {
+      const { orderDir = 'ASC', limit, offset } = options
+      const vars: Record<string, unknown> = this.normalizeMutationData(filter)
+      let sql = `SELECT * FROM ${table}`
+      if (filterKeys.length > 0) {
+        const conditions = filterKeys.map((key) => `${key} = $${key}`).join(' AND ')
+        sql += ` WHERE ${conditions}`
+      }
+      sql += ` ORDER BY ${orderBy} ${orderDir}`
+      if (limit !== undefined) {
+        sql += ' LIMIT $limitParam'
+        vars.limitParam = limit
+      }
+      if (offset !== undefined) {
+        sql += ' START $offsetParam'
+        vars.offsetParam = offset
+      }
+      const rows = await this.query<unknown>(new BoundQuery(sql, vars))
+      return rows.map((row) => schema.parse(row))
+    }
+
+    try {
+      let query = client.select<unknown>(new Table(table))
+      if (selection) {
+        query = query.where(selection)
+      }
+      if (options?.offset !== undefined) {
+        query = query.start(options.offset)
+      }
+      if (options?.limit !== undefined) {
+        query = query.limit(options.limit)
+      }
+
+      const rows = await query
+      return rows.map((row) => schema.parse(row))
+    } catch (error) {
+      this.toSurrealError(error, `SELECT * FROM ${table}`)
+    }
+  }
+
+  async create<T extends z.ZodType>(
+    table: DatabaseTable,
+    data: Record<string, unknown>,
+    schema: T,
+  ): Promise<z.infer<T>> {
+    const keys = Object.keys(data)
+    if (keys.length === 0) {
+      throw new SurrealDBError(`Cannot create record in ${table} with empty data`)
+    }
+
+    const client = await this.ensureConnected()
+
+    try {
+      const created = await client
+        .create<unknown>(new Table(table))
+        .content(this.normalizeMutationData(data))
+        .output('after')
+      const first = Array.isArray(created) ? created.at(0) : created
+
+      if (!first) {
+        throw new SurrealDBError(`Failed to create record in ${table}`)
+      }
+
+      return schema.parse(first)
+    } catch (error) {
+      this.toSurrealError(error, `CREATE ${table}`)
+    }
+  }
+
+  async createWithId<T extends z.ZodType>(
+    table: DatabaseTable,
+    id: unknown,
+    data: Record<string, unknown>,
+    schema: T,
+  ): Promise<z.infer<T>> {
+    const keys = Object.keys(data)
+    if (keys.length === 0) {
+      throw new SurrealDBError(`Cannot create record in ${table} with empty data`)
+    }
+
+    const recordId = this.normalizeRecordId(id, table)
+    const client = await this.ensureConnected()
+
+    try {
+      const created = await client.create<unknown>(recordId).content(this.normalizeMutationData(data)).output('after')
+      return schema.parse(created)
+    } catch (error) {
+      this.toSurrealError(error, `CREATE ${recordId.toString()}`)
+    }
+  }
+
+  async update<T extends z.ZodType>(
+    table: DatabaseTable,
+    id: unknown,
+    data: Record<string, unknown>,
+    schema: T,
+    options?: { mutation?: Mutation },
+  ): Promise<z.infer<T> | null> {
+    const recordId = this.normalizeRecordId(id, table)
+
+    const keys = Object.keys(data)
+    if (keys.length === 0) {
+      throw new SurrealDBError('Cannot update record with empty data')
+    }
+
+    const client = await this.ensureConnected()
+    const mutation = options?.mutation ?? 'merge'
+
+    try {
+      const builder = client.update<unknown>(recordId)
+      const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
+      const updated = await configured.output('after')
+      return updated ? schema.parse(updated) : null
+    } catch (error) {
+      this.toSurrealError(error, `UPDATE ${recordId.toString()}`)
+    }
+  }
+
+  async upsert<T extends z.ZodType>(
+    table: DatabaseTable,
+    id: unknown,
+    data: Record<string, unknown>,
+    schema: T,
+    options?: { mutation?: Mutation },
+  ): Promise<z.infer<T>> {
+    const recordId = this.normalizeRecordId(id, table)
+    const keys = Object.keys(data)
+    if (keys.length === 0) {
+      throw new SurrealDBError('Cannot upsert record with empty data')
+    }
+
+    const client = await this.ensureConnected()
+    const mutation = options?.mutation ?? 'merge'
+
+    try {
+      const builder = client.upsert<unknown>(recordId)
+      const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
+      const upserted = await configured.output('after')
+      if (!upserted) {
+        throw new SurrealDBError(`Failed to upsert record in ${table}`)
+      }
+      return schema.parse(upserted)
+    } catch (error) {
+      this.toSurrealError(error, `UPSERT ${recordId.toString()}`)
+    }
+  }
+
+  async deleteById(table: DatabaseTable, id: unknown): Promise<boolean> {
+    const recordId = this.normalizeRecordId(id, table)
+    const client = await this.ensureConnected()
+
+    try {
+      const matched = await client.select<{ id: unknown }>(new Table(table)).where(eq('id', recordId)).limit(1)
+      if (matched.length === 0) {
+        return false
+      }
+      await client.delete<unknown>(recordId).output('before')
+      return true
+    } catch (error) {
+      this.toSurrealError(error, `DELETE ${recordId.toString()}`)
+    }
+  }
+
+  async deleteWhere(table: DatabaseTable, filter: Record<string, unknown>): Promise<number> {
+    const filterKeys = Object.keys(filter)
+    if (filterKeys.length === 0) {
+      throw new SurrealDBError(`Refusing to delete all records in ${table} without a filter`)
+    }
+
+    const selection = this.buildFilterExpression(filter)
+    if (!selection) {
+      throw new SurrealDBError(`Invalid delete filter for table ${table}`)
+    }
+
+    const client = await this.ensureConnected()
+
+    try {
+      const matched = await client.select<{ id: unknown }>(new Table(table)).where(selection)
+      if (matched.length === 0) {
+        return 0
+      }
+
+      for (const row of matched) {
+        const id = this.normalizeRecordId(row.id, table)
+        await client.delete(id)
+      }
+
+      return matched.length
+    } catch (error) {
+      this.toSurrealError(error, `DELETE ${table} WHERE ...`)
+    }
+  }
+
+  async updateWhere(table: DatabaseTable, where: ExprLike, data: Record<string, unknown>): Promise<number> {
+    if (!where) {
+      throw new SurrealDBError(`Refusing to update records in ${table} without a where clause`)
+    }
+    const keys = Object.keys(data)
+    if (keys.length === 0) {
+      throw new SurrealDBError(`Cannot update records in ${table} with empty data`)
+    }
+
+    const client = await this.ensureConnected()
+
+    try {
+      const updated = await client
+        .update<unknown>(new Table(table))
+        .where(where)
+        .merge(this.normalizeMutationData(data))
+        .output('after')
+      if (Array.isArray(updated)) {
+        return updated.length
+      }
+      return 1
+    } catch (error) {
+      this.toSurrealError(error, `UPDATE ${table} WHERE ...`)
+    }
+  }
+
+  async insert<T extends Record<string, unknown>>(
+    table: DatabaseTable,
+    data: Values<T> | Array<Values<T>>,
+  ): Promise<T[]> {
+    const client = await this.ensureConnected()
+
+    try {
+      const normalized = Array.isArray(data)
+        ? data.map((item) => this.normalizeMutationData(item as Record<string, unknown>))
+        : this.normalizeMutationData(data as Record<string, unknown>)
+      const inserted = await client
+        .insert<T>(new Table(table), normalized as Values<T> | Array<Values<T>>)
+        .output('after')
+      return inserted as T[]
+    } catch (error) {
+      this.toSurrealError(error, `INSERT ${table}`)
+    }
+  }
+
+  async relate<T extends Record<string, unknown>>(
+    from: RecordIdInput,
+    edgeTable: DatabaseTable,
+    to: RecordIdInput,
+    data?: Values<T>,
+  ): Promise<T | null> {
+    const client = await this.ensureConnected()
+    const fromRef = ensureRecordId(from)
+    const toRef = ensureRecordId(to)
+
+    try {
+      const normalizedData = data
+        ? (this.normalizeMutationData(data as Record<string, unknown>) as Values<T>)
+        : undefined
+      const related = (await client.relate<T>(fromRef, new Table(edgeTable), toRef, normalizedData).output('after')) as
+        | T
+        | T[]
+        | null
+      if (related === null) {
+        return null
+      }
+      if (Array.isArray(related)) {
+        return related.at(0) ?? null
+      }
+      return related
+    } catch (error) {
+      this.toSurrealError(error, `RELATE ${fromRef.toString()}->${edgeTable}->${toRef.toString()}`)
+    }
+  }
+
+  async beginTransaction(): Promise<DatabaseTransaction> {
+    const client = await this.ensureConnected()
+    try {
+      return this.wrapTransaction(await client.beginTransaction())
+    } catch (error) {
+      this.toSurrealError(error, 'BEGIN TRANSACTION')
+    }
+  }
+
+  async withTransaction<T>(work: (tx: DatabaseTransaction) => Promise<T>): Promise<T> {
+    const tx = await this.beginTransaction()
+    try {
+      const result = await work(tx)
+      await tx.commit()
+      return result
+    } catch (error) {
+      try {
+        await tx.cancel()
+      } catch (cancelError) {
+        this.logger?.warn?.(
+          `Failed to cancel transaction after error: ${
+            cancelError instanceof Error ? cancelError.message : String(cancelError)
+          }`,
+        )
+      }
+      throw error
+    }
+  }
+}
+
+let currentDatabaseService: SurrealDBService | undefined
+const databaseServiceOverrides = new Map<PropertyKey, unknown>()
+
+function bindTargetMethod(
+  target: Record<PropertyKey, unknown>,
+  value: (...args: unknown[]) => unknown,
+): (...args: unknown[]) => unknown {
+  return (...args) => Reflect.apply(value, target, args)
+}
+
+function resolveConfiguredDatabaseService(): SurrealDBService {
+  if (!currentDatabaseService) {
+    throw new SurrealDBError('Database service not configured')
+  }
+
+  return currentDatabaseService
+}
+
+export const databaseService = new Proxy({} as SurrealDBService, {
+  get(_target, property) {
+    if (databaseServiceOverrides.has(property)) {
+      return databaseServiceOverrides.get(property)
+    }
+
+    const target = resolveConfiguredDatabaseService() as unknown as Record<PropertyKey, unknown>
+    const value = target[property]
+    if (typeof value === 'function') {
+      return bindTargetMethod(target, value as (...args: unknown[]) => unknown)
+    }
+
+    return value
+  },
+  set(_target, property, value) {
+    databaseServiceOverrides.set(property, value)
+    return true
+  },
+})
+
+export function setDatabaseService(db: SurrealDBService): void {
+  if (db === databaseService) {
+    return
+  }
+
+  currentDatabaseService = db
+}
+
+export function getDatabaseService(): SurrealDBService | undefined {
+  return currentDatabaseService
+}