@lota-sdk/core 0.4.7 → 0.4.9

package/src/db/service.ts

@@ -1,34 +1,35 @@
-import {
-  BoundQuery,
-  RecordId,
-  ServerError,
-  StringRecordId,
-  Surreal,
-  Table,
-  and,
-  createRemoteEngines,
-  eq,
-} from 'surrealdb'
-import type { ExprLike, Mutation, SurrealTransaction, Values } from 'surrealdb'
+import { Duration, Effect, Schedule } from 'effect'
+import { BoundQuery, ServerError, Surreal, Table, createRemoteEngines } from 'surrealdb'
+import type { ExprLike, SurrealTransaction, Values } from 'surrealdb'
+import { ZodError } from 'zod'
 import type { z } from 'zod'
 
 import { serverLogger } from '../config/logger'
-import { withTimeout } from '../utils/async'
-import { isRecord } from '../utils/string'
+import type { AwaitableEffect } from '../effect/awaitable-effect'
+import { toAwaitableEffect } from '../effect/awaitable-effect'
+import { getErrorMessage } from '../utils/errors'
 import type { RecordIdInput } from './record-id'
-import { ensureRecordId, isSurrealRecordIdValue } from './record-id'
+import { ensureRecordId } from './record-id'
+import {
+  assertValidIdentifier,
+  buildBoundFilterClauses,
+  buildFilterExpression,
+  configureMutation,
+  describeInvalidValue,
+  normalizeBoundQuery,
+  normalizeCreateTarget,
+  normalizeMutationData,
+  normalizeQueryRows,
+  normalizeRecordIdForTable,
+  normalizeSurrealValue,
+  normalizeTableValue,
+  normalizeTransactionQuery,
+  normalizeTransactionRecordId,
+  SurrealDBError,
+} from './service-normalization'
+import type { RecordMutation } from './service-normalization'
 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'
-  }
-}
+import { isRetriableTransactionConflict } from './transaction-conflict'
 
 export interface SurrealDatabaseConfig {
   url: string
@@ -51,75 +52,88 @@ interface FindManyOptions {
   orderDir?: 'ASC' | 'DESC'
 }
 
-type MutationBuilder = {
+type MutationBuilderSource = {
+  content: (data: Record<string, unknown>) => MutationBuilderSource
+  replace: (data: Record<string, unknown>) => MutationBuilderSource
+  merge: (data: Record<string, unknown>) => MutationBuilderSource
+  output: (mode: 'after' | 'before') => unknown
+}
+
+export type MutationBuilder = {
   content: (data: Record<string, unknown>) => MutationBuilder
   replace: (data: Record<string, unknown>) => MutationBuilder
   merge: (data: Record<string, unknown>) => MutationBuilder
-  output: (mode: 'after' | 'before') => Promise<unknown>
+  output: (mode: 'after' | 'before') => AwaitableEffect<unknown, SurrealDBError>
 }
 
-type RecordMutation = Extract<Mutation, 'content' | 'replace' | 'merge'>
+type CreateBuilderSource = {
+  content: (data: Record<string, unknown>) => CreateBuilderSource
+  output: (mode: 'after' | 'before') => unknown
+}
 
 export type CreateMutationBuilder = {
   content: (data: Record<string, unknown>) => CreateMutationBuilder
-  output: (mode: 'after' | 'before') => Promise<unknown>
+  output: (mode: 'after' | 'before') => AwaitableEffect<unknown, SurrealDBError>
 }
 
 export interface DatabaseTransaction {
-  query: (query: unknown) => Promise<unknown>
+  query: (query: unknown) => AwaitableEffect<unknown, SurrealDBError>
   create: (target: unknown) => CreateMutationBuilder
   update: (target: unknown) => MutationBuilder
-  delete: (target: unknown) => Promise<unknown>
-  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: RecordMutation,
-  data: Record<string, unknown>,
-): MutationBuilder {
-  if (mutation === 'content') {
-    return builder.content(data)
-  }
-  if (mutation === 'replace') {
-    return builder.replace(data)
-  }
-  return builder.merge(data)
+  delete: (target: unknown) => AwaitableEffect<unknown, SurrealDBError>
+  relate: (
+    from: unknown,
+    edgeTable: unknown,
+    to: unknown,
+    data?: Values<Record<string, unknown>>,
+  ) => AwaitableEffect<unknown, SurrealDBError>
+  commit: () => AwaitableEffect<void, SurrealDBError>
+  cancel: () => AwaitableEffect<void, SurrealDBError>
 }
 
 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
 
+function isRetriableConnectError(error: unknown): boolean {
+  if (isRetriableTransactionConflict(error)) {
+    return true
+  }
+
+  const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error)
+  return /(timed out connecting to SurrealDB|ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|network|socket|connection)/i.test(
+    message,
+  )
+}
+
 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 {
+  private toSurrealError(error: unknown, query?: string): SurrealDBError | ZodError {
     if (error instanceof SurrealDBError) {
-      throw error
+      return error
+    }
+
+    if (error instanceof ZodError) {
+      return error
     }
 
     if (error instanceof ServerError) {
-      throw new SurrealDBError(`${error.name}: ${error.message}`, query, { cause: error })
+      return new SurrealDBError({ message: `${error.name}: ${error.message}`, query: query, cause: error })
     }
 
     if (error instanceof Error) {
-      throw new SurrealDBError(error.message, query, { cause: error })
+      return new SurrealDBError({ message: error.message, query: query, cause: error })
     }
 
-    throw new SurrealDBError(String(error), query)
+    return new SurrealDBError({ message: String(error), query })
   }
-
   private isEmbeddedEngine(url: string) {
     return (
       url === 'mem://' ||
@@ -130,76 +144,77 @@ export class SurrealDBService {
     )
   }
 
-  private async getOrCreateClient(): Promise<Surreal> {
+  private getOrCreateClient(): Effect.Effect<Surreal, SurrealDBError> {
     if (this.client) {
-      return this.client
+      return Effect.succeed(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
-  }
+    const self = this
+    return Effect.gen(function* () {
+      if (self.client) {
+        return self.client
+      }
 
-  private async resetClient(): Promise<void> {
-    if (!this.client) {
-      return
-    }
+      if (self.isEmbeddedEngine(self.config.url)) {
+        const { createNodeEngines } = yield* Effect.tryPromise({
+          try: () => import('@surrealdb/node'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to load embedded SurrealDB engine: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        self.client = new Surreal({
+          engines: { ...createRemoteEngines(), ...createNodeEngines() } as NonNullable<
+            ConstructorParameters<typeof Surreal>[0]
+          >['engines'],
+          codecOptions,
+        })
+        return self.client
+      }
 
-    try {
-      await this.client.close()
-    } catch (error) {
-      serverLogger.warn`Failed to close database client: ${error}`
-    } finally {
-      this.client = null
-    }
+      self.client = new Surreal({ engines: createRemoteEngines(), codecOptions })
+      return self.client
+    })
   }
 
-  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')
+  private resetClient(): Effect.Effect<void, never> {
+    if (this.client === null) {
+      return Effect.void
+    }
+
+    const client = this.client
+
+    return Effect.tryPromise({
+      try: () => client.close(),
+      catch: (error) =>
+        new SurrealDBError({ message: `Failed to close database client: ${getErrorMessage(error)}`, cause: error }),
+    }).pipe(
+      Effect.catch((error: SurrealDBError) =>
+        Effect.sync(() => {
+          serverLogger.warn`Failed to close database client: ${error.message}`
+        }),
+      ),
+      Effect.asVoid,
+      Effect.ensuring(
+        Effect.sync(() => {
+          this.client = null
+        }),
+      ),
     )
   }
 
-  async connect(): Promise<void> {
+  connect(): AwaitableEffect<void, SurrealDBError> {
     if (this.isConnected) {
-      return
-    }
-
-    if (this.connectPromise) {
-      await this.connectPromise
-      return
+      return toAwaitableEffect(Effect.void)
     }
 
-    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(
+    const connectEffect = this.getOrCreateClient().pipe(
+      Effect.flatMap((client) =>
+        Effect.tryPromise({
+          try: () =>
             client.connect(this.config.url, {
               namespace: this.config.namespace,
               database: this.config.database,
@@ -207,356 +222,258 @@ export class SurrealDBService {
                 ? undefined
                 : { username: this.config.username ?? '', password: this.config.password ?? '' },
             }),
-            CONNECT_ATTEMPT_TIMEOUT_MS,
-            `SurrealDB connect (${this.config.url})`,
-          )
-
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to connect to SurrealDB (${this.config.url}): ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        }).pipe(
+          Effect.timeout(Duration.millis(CONNECT_ATTEMPT_TIMEOUT_MS)),
+          Effect.catchTag('TimeoutError', () =>
+            Effect.fail(new SurrealDBError({ message: `Timed out connecting to SurrealDB (${this.config.url})` })),
+          ),
+        ),
+      ),
+      Effect.tap(() =>
+        Effect.sync(() => {
           this.isConnected = true
           this.logger?.info?.('Connected to SurrealDB')
-          return
-        } catch (error) {
-          lastError = error
+        }),
+      ),
+      Effect.tapError(() =>
+        Effect.sync(() => {
           this.isConnected = false
-          await this.resetClient()
+        }).pipe(Effect.andThen(this.resetClient())),
+      ),
+      Effect.retry({
+        times: CONNECT_MAX_ATTEMPTS - 1,
+        schedule: Schedule.jittered(Schedule.exponential(Duration.millis(CONNECT_RETRY_BASE_DELAY_MS), 2)),
+        while: isRetriableConnectError,
+      }),
+      Effect.asVoid,
+    )
 
-          const retriable = this.isRetriableConnectConflict(error)
-          const hasMoreAttempts = attempt < CONNECT_MAX_ATTEMPTS
-          if (!retriable || !hasMoreAttempts) {
-            break
-          }
+    return toAwaitableEffect(connectEffect)
+  }
 
-          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)
+  disconnect(): AwaitableEffect<void, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        if (!self.isConnected) {
+          return
         }
-      }
 
-      return this.toSurrealError(lastError)
-    })()
+        self.isConnected = false
 
-    try {
-      await this.connectPromise
-    } finally {
-      this.connectPromise = null
-    }
-  }
+        const client = self.client
+        if (!client) {
+          self.client = null
+          return
+        }
 
-  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)}`,
+        yield* Effect.tryPromise({
+          try: () => client.close(),
+          catch: (error) =>
+            new SurrealDBError({ message: `Failed to close database client: ${getErrorMessage(error)}`, cause: error }),
+        }).pipe(
+          Effect.ensuring(
+            Effect.sync(() => {
+              self.client = null
+            }),
+          ),
         )
-        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')
+  private ensureConnectedEffect(query?: string): Effect.Effect<Surreal, SurrealDBError, never> {
+    if (this.client === null || !this.isConnected) {
+      return this.connect().pipe(
+        Effect.flatMap(() => this.getOrCreateClient()),
+        Effect.mapError((error) =>
+          error instanceof SurrealDBError
+            ? error
+            : new SurrealDBError({ message: 'Database not connected', query, cause: error }),
+        ),
+      )
     }
 
-    return this.client
+    return Effect.succeed(this.client)
   }
 
   private normalizeRecordId(id: unknown, table: DatabaseTable): ReturnType<typeof ensureRecordId> {
-    try {
-      const recordId = ensureRecordId(id as RecordIdInput, table)
-      const resolvedTable = String(recordId.table)
-      if (resolvedTable !== table) {
-        throw new SurrealDBError(`Record id table mismatch: expected "${table}" but got "${resolvedTable}"`)
-      }
-      return recordId
-    } catch (error) {
-      if (error instanceof SurrealDBError) {
-        throw 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}"`)
-    }
+    return normalizeRecordIdForTable(id, table)
   }
 
   private normalizeQueryRows(statement: unknown, schema?: z.ZodTypeAny): unknown[] {
-    if (Array.isArray(statement)) {
-      return schema ? statement.map((row) => this.parseSchema(schema, row)) : (statement as unknown[])
-    }
-    if (statement === null || statement === undefined) {
-      return []
-    }
-    return schema ? [this.parseSchema(schema, statement)] : [statement]
+    return normalizeQueryRows(statement, schema, (schemaValue, value) => this.parseSchema(schemaValue, value))
   }
 
   private normalizeParseValue(value: unknown): unknown {
-    if (
-      value instanceof Date ||
-      value instanceof RecordId ||
-      value instanceof StringRecordId ||
-      value instanceof Table
-    ) {
-      return value
-    }
-
-    if (Array.isArray(value)) {
-      return value.map((entry) => this.normalizeParseValue(entry))
-    }
-
-    if (isSurrealRecordIdValue(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
-
-    if (!isRecord(value)) {
-      return value
-    }
-
-    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, this.normalizeParseValue(entry)]))
+    return normalizeSurrealValue(value)
   }
 
   private parseSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown): z.infer<TSchema> {
     return schema.parse(this.normalizeParseValue(value))
   }
 
-  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]
+  private parseOptionalSchema<TSchema extends z.ZodTypeAny>(schema: TSchema, value: unknown): z.infer<TSchema> | null {
+    if (value === null || value === undefined) {
+      return null
     }
 
-    return and(...expressions)
+    return this.parseSchema(schema, value)
   }
 
-  private assertValidIdentifier(name: string, context: string): void {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(name)) {
-      throw new SurrealDBError(`Invalid ${context}: "${name}"`)
-    }
+  private buildFilterExpression(filter: Record<string, unknown>): ExprLike | undefined {
+    return buildFilterExpression(filter)
   }
 
   private buildBoundFilterClauses(filter: Record<string, unknown>): {
     clause: string
     bindings: Record<string, unknown>
   } {
-    const entries = Object.entries(filter)
-    if (entries.length === 0) {
-      throw new SurrealDBError('Expected a non-empty filter')
-    }
-
-    const bindings: Record<string, unknown> = {}
-    const clauses = entries.map(([field, value], index) => {
-      this.assertValidIdentifier(field, 'filter field')
-
-      const bindingKey = `filter_${index}`
-      bindings[bindingKey] = this.normalizeRuntimeValue(value)
-      return `${field} = $${bindingKey}`
-    })
-
-    return { clause: clauses.join(' AND '), bindings }
+    return buildBoundFilterClauses(filter)
   }
 
-  private normalizeBoundQuery(query: BoundQuery): BoundQuery {
-    return new BoundQuery(query.query, this.normalizeBindings(query.bindings))
+  private normalizeBoundQuery<T extends unknown[] = unknown[]>(query: BoundQuery<T>): BoundQuery<T> {
+    return normalizeBoundQuery(query)
   }
 
-  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 (isSurrealRecordIdValue(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
-
-    if (!isRecord(value)) {
-      return value
-    }
-
-    if ('tb' in value && 'id' in value && Object.keys(value).length === 2) {
-      return ensureRecordId(value as unknown as RecordIdInput)
-    }
-
-    const entries = Object.entries(value)
-    if (entries.length === 0) {
-      return value
-    }
-
-    return Object.fromEntries(entries.map(([key, entryValue]) => [key, this.normalizeRuntimeValue(entryValue)]))
-  }
-
-  // Cast is safe: normalizeRuntimeValue preserves Record shape when input is a Record
-  // (non-array objects are mapped entry-by-entry and returned as Object.fromEntries)
-  private normalizeBindings(bindings?: Record<string, unknown>): Record<string, unknown> | undefined {
-    if (!bindings) {
-      return undefined
-    }
-
-    return this.normalizeRuntimeValue(bindings) as Record<string, unknown>
-  }
-
-  private normalizeMutationFieldValue(value: unknown): unknown {
-    if (value === undefined) {
-      return undefined
-    }
-
-    if (value === null) {
-      return null
-    }
-
-    return this.normalizeRuntimeValue(value)
+  private normalizeTransactionQuery(query: unknown): BoundQuery {
+    return normalizeTransactionQuery(query)
   }
 
-  // Cast is safe: normalizeRuntimeValue preserves Record shape when input is a Record
   private normalizeMutationData(data: Record<string, unknown>): Record<string, unknown> {
-    return Object.fromEntries(
-      Object.entries(data)
-        .map(([key, value]) => [key, this.normalizeMutationFieldValue(value)] as const)
-        .filter((entry): entry is readonly [string, unknown] => entry[1] !== undefined),
-    ) as Record<string, unknown>
-  }
-
-  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)
-    }
-
-    throw new SurrealDBError('Invalid table value')
+    return normalizeMutationData(data)
   }
 
-  private isRecordIdLike(value: unknown): boolean {
-    if (value instanceof RecordId || value instanceof StringRecordId) {
-      return true
-    }
-
-    if (isSurrealRecordIdValue(value)) {
-      return true
-    }
-
-    if (typeof value === 'string') {
-      return /^[a-zA-Z][a-zA-Z0-9_]*:/.test(value)
-    }
-
-    if (value && typeof value === 'object') {
-      const record = value as { tb?: unknown; id?: unknown }
-      return typeof record.tb === 'string' && record.id !== undefined && Object.keys(value).length === 2
-    }
-
-    return false
+  private normalizeTableValue(value: unknown): Table<string> {
+    return normalizeTableValue(value)
   }
 
-  private normalizeCreateTarget(value: unknown): Table | RecordId {
-    if (this.isRecordIdLike(value)) {
-      return ensureRecordId(value as RecordIdInput)
-    }
-
-    return this.normalizeTableValue(value)
+  private normalizeCreateTarget(value: unknown): Table<string> | ReturnType<typeof ensureRecordId> {
+    return normalizeCreateTarget(value)
   }
 
-  private wrapMutationBuilder(builder: MutationBuilder): MutationBuilder {
+  private wrapMutationBuilder(builder: MutationBuilderSource): MutationBuilder {
     return {
       content: (data) => this.wrapMutationBuilder(builder.content(this.normalizeMutationData(data))),
       replace: (data) => this.wrapMutationBuilder(builder.replace(this.normalizeMutationData(data))),
       merge: (data) => this.wrapMutationBuilder(builder.merge(this.normalizeMutationData(data))),
-      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
+      output: (mode) =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => Promise.resolve(builder.output(mode)),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to finish mutation output: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          }).pipe(Effect.map((value) => this.normalizeParseValue(value))),
+        ),
     }
   }
 
-  private wrapCreateBuilder(builder: CreateMutationBuilder): CreateMutationBuilder {
+  private wrapCreateBuilder(builder: CreateBuilderSource): CreateMutationBuilder {
     return {
       content: (data) => this.wrapCreateBuilder(builder.content(this.normalizeMutationData(data))),
-      output: async (mode) => this.normalizeParseValue(await builder.output(mode)),
+      output: (mode) =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => Promise.resolve(builder.output(mode)),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to finish create output: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          }).pipe(Effect.map((value) => this.normalizeParseValue(value))),
+        ),
     }
   }
 
   private wrapTransaction(tx: SurrealTransaction): DatabaseTransaction {
+    const self = this
     return {
-      query: async (query: unknown) => {
-        const boundQuery = this.normalizeBoundQuery(query as BoundQuery)
-        const queryText = this.resolveQueryText(boundQuery)
-
-        try {
-          const responses = await tx.query(boundQuery).responses()
-          const first = responses.at(0)
-          if (!first) {
-            return []
-          }
-          if (!first.success) {
-            throw new SurrealDBError(first.error.message, queryText, { cause: first.error })
-          }
-
-          return this.normalizeQueryRows(first.result)
-        } catch (error) {
-          return this.toSurrealError(error, queryText)
-        }
+      query: (query: unknown) => {
+        const boundQuery = self.normalizeTransactionQuery(query)
+        const queryText = self.resolveQueryText(boundQuery)
+        return toAwaitableEffect(
+          Effect.gen(function* () {
+            const responses = yield* Effect.tryPromise({
+              try: () => tx.query(boundQuery).responses(),
+              catch: (error) =>
+                new SurrealDBError({
+                  message: `Failed to run transaction query: ${getErrorMessage(error)}`,
+                  query: queryText,
+                  cause: error,
+                }),
+            })
+            const first = responses.at(0)
+            if (!first) {
+              return []
+            }
+            if (!first.success) {
+              return yield* new SurrealDBError({ message: first.error.message, query: queryText, cause: first.error })
+            }
+
+            return self.normalizeQueryRows(first.result)
+          }),
+        )
       },
       create: (target: unknown) => {
-        const normalizedTarget = this.normalizeCreateTarget(target)
-        const builder = normalizedTarget instanceof Table ? tx.create(normalizedTarget) : tx.create(normalizedTarget)
-        // Cast needed: SurrealDB SDK transaction builder type differs nominally from internal CreateMutationBuilder interface
-        return this.wrapCreateBuilder(builder as unknown as CreateMutationBuilder)
+        const normalizedTarget = self.normalizeCreateTarget(target)
+        const builder: CreateBuilderSource =
+          normalizedTarget instanceof Table ? tx.create(normalizedTarget) : tx.create(normalizedTarget)
+        return self.wrapCreateBuilder(builder)
       },
       update: (target: unknown) =>
-        // Cast needed: SurrealDB SDK transaction builder type differs nominally from internal MutationBuilder interface
-        this.wrapMutationBuilder(tx.update(ensureRecordId(target as RecordIdInput)) as unknown as MutationBuilder),
-      delete: async (target: unknown) =>
-        this.normalizeParseValue(await tx.delete(ensureRecordId(target as RecordIdInput))),
-      relate: async (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
-        this.normalizeParseValue(
-          await 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,
-          ),
+        self.wrapMutationBuilder(tx.update(normalizeTransactionRecordId(target, 'transaction update'))),
+      delete: (target: unknown) =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => tx.delete(normalizeTransactionRecordId(target, 'transaction delete')),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to delete transaction target: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          }).pipe(Effect.map((value) => this.normalizeParseValue(value))),
+        ),
+      relate: (from: unknown, edgeTable: unknown, to: unknown, data?: Values<Record<string, unknown>>) =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () =>
+              tx.relate(
+                normalizeTransactionRecordId(from, 'transaction relate source'),
+                self.normalizeTableValue(edgeTable),
+                normalizeTransactionRecordId(to, 'transaction relate target'),
+                data ? self.normalizeMutationData(data as Record<string, unknown>) : undefined,
+              ),
+            catch: (error) =>
+              new SurrealDBError({
+                message: `Failed to relate transaction records: ${getErrorMessage(error)}`,
+                cause: error,
+              }),
+          }).pipe(Effect.map((value) => this.normalizeParseValue(value))),
+        ),
+      commit: () =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => tx.commit(),
+            catch: (error) =>
+              new SurrealDBError({ message: `Failed to commit transaction: ${getErrorMessage(error)}`, cause: error }),
+          }),
+        ),
+      cancel: () =>
+        toAwaitableEffect(
+          Effect.tryPromise({
+            try: () => tx.cancel(),
+            catch: (error) =>
+              new SurrealDBError({ message: `Failed to cancel transaction: ${getErrorMessage(error)}`, cause: error }),
+          }),
         ),
-      commit: () => tx.commit(),
-      cancel: () => tx.cancel(),
     }
   }
 
@@ -564,459 +481,507 @@ export class SurrealDBService {
     return query.query
   }
 
-  async query<T>(query: BoundQuery): Promise<T[]> {
-    const statements = await this.queryAll<T>(query)
-    return statements.at(0) ?? []
+  query<T>(query: BoundQuery): AwaitableEffect<T[], SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const boundQuery = self.normalizeBoundQuery(query)
+        const statements = yield* self.queryAll<T>(boundQuery)
+        return statements.at(0) ?? []
+      }),
+    )
   }
 
-  async queryAll<T>(query: BoundQuery, schema?: z.ZodTypeAny): 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(response.result, schema) as T[]
-      })
-    } catch (error) {
-      return this.toSurrealError(error, queryText)
-    }
+  queryAll<T>(query: BoundQuery, schema?: z.ZodTypeAny): AwaitableEffect<T[][], SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const boundQuery = self.normalizeBoundQuery(query)
+        const queryText = self.resolveQueryText(boundQuery)
+        const client = yield* self.ensureConnectedEffect(queryText)
+        const responses = yield* Effect.tryPromise({
+          try: () => client.query(boundQuery).responses(),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to run query: ${getErrorMessage(error)}`,
+              query: queryText,
+              cause: error,
+            }),
+        })
+        return yield* Effect.forEach(responses, (response, index) =>
+          Effect.gen(function* () {
+            if (!response.success) {
+              const failure = response.error
+              return yield* new SurrealDBError({
+                message: `Statement ${index + 1}: ${failure.message}`,
+                query: queryText,
+                cause: failure,
+              })
+            }
+            return self.normalizeQueryRows(response.result, schema) as T[]
+          }),
+        )
+      }),
+    )
   }
 
-  async queryOne<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T> | null> {
-    const results = await this.query<unknown>(query)
-    const first = results.at(0)
-    return first ? this.parseSchema(schema, first) : null
+  queryOne<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const boundQuery = self.normalizeBoundQuery(query)
+        const results = yield* self.query<unknown>(boundQuery)
+        const first = results.at(0)
+        return first ? self.parseSchema(schema, first) : null
+      }),
+    )
   }
 
-  async queryMany<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): Promise<z.infer<T>[]> {
-    const results = await this.query<unknown>(query)
-    return results.map((row) => this.parseSchema(schema, row))
+  queryMany<T extends z.ZodTypeAny>(query: BoundQuery, schema: T): AwaitableEffect<z.infer<T>[], SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const boundQuery = self.normalizeBoundQuery(query)
+        const results = yield* self.query<unknown>(boundQuery)
+        return results.map((row) => self.parseSchema(schema, row))
+      }),
+    )
   }
 
-  private async runSqlFile(file: Bun.BunFile): Promise<void> {
-    const sql = (await file.text()).trim()
-    if (!sql) {
-      return
-    }
+  private runSqlFile(file: Bun.BunFile): Effect.Effect<void, SurrealDBError> {
+    const self = this
+    return Effect.gen(function* () {
+      const sql = (yield* Effect.tryPromise({
+        try: () => file.text(),
+        catch: (error) =>
+          new SurrealDBError({ message: `Failed to read schema file: ${getErrorMessage(error)}`, cause: error }),
+      })).trim()
+      if (!sql) {
+        return
+      }
 
-    await this.queryAll<unknown>(new BoundQuery(sql))
+      yield* self.queryAll<unknown>(new BoundQuery(sql))
+    })
   }
 
-  async applySchema(schemaFiles: readonly Bun.BunFile[]): Promise<void> {
-    for (const schemaFile of schemaFiles) {
-      await this.runSqlFile(schemaFile)
-    }
+  applySchema(schemaFiles: readonly Bun.BunFile[]): AwaitableEffect<void, SurrealDBError> {
+    return toAwaitableEffect(
+      Effect.forEach(schemaFiles, (schemaFile) => this.runSqlFile(schemaFile), { discard: true }),
+    )
   }
 
-  async findOne<T extends z.ZodTypeAny>(
+  findOne<T extends z.ZodTypeAny>(
     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)
-      }
+  ): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const selection = self.buildFilterExpression(filter)
+        const client = yield* self.ensureConnectedEffect(`SELECT * FROM ${table} LIMIT 1`)
+        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 ? this.parseSchema(schema, first) : null
-    } catch (error) {
-      return this.toSurrealError(error, `SELECT * FROM ${table} LIMIT 1`)
-    }
+        const rows = yield* Effect.tryPromise({
+          try: () => query.limit(1),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to find record in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        const first = rows.at(0)
+        return first ? self.parseSchema(schema, first) : null
+      }),
+    )
   }
 
-  async findMany<T extends z.ZodTypeAny>(
+  findMany<T extends z.ZodTypeAny>(
     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 (orderBy !== undefined) {
-      this.assertValidIdentifier(orderBy, 'orderBy field')
-      this.assertValidIdentifier(table, 'table name')
-      for (const key of filterKeys) {
-        this.assertValidIdentifier(key, 'filter field')
-      }
-      const rawOrderDir: unknown = options?.orderDir
-      if (rawOrderDir !== undefined && rawOrderDir !== 'ASC' && rawOrderDir !== 'DESC') {
-        throw new SurrealDBError(`Invalid orderDir value: ${this.describeInvalidValue(rawOrderDir)}`)
-      }
-      const orderDir = rawOrderDir ?? 'ASC'
-      const limit = options?.limit
-      const offset = options?.offset
-      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) => this.parseSchema(schema, 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) => this.parseSchema(schema, row))
-    } catch (error) {
-      return this.toSurrealError(error, `SELECT * FROM ${table}`)
-    }
-  }
+  ): AwaitableEffect<z.infer<T>[], SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const filterKeys = Object.keys(filter)
+        const selection = self.buildFilterExpression(filter)
+        const orderBy = options?.orderBy
+
+        if (orderBy !== undefined) {
+          assertValidIdentifier(orderBy, 'orderBy field')
+          assertValidIdentifier(table, 'table name')
+          for (const key of filterKeys) {
+            assertValidIdentifier(key, 'filter field')
+          }
+          const rawOrderDir: unknown = options?.orderDir
+          if (rawOrderDir !== undefined && rawOrderDir !== 'ASC' && rawOrderDir !== 'DESC') {
+            return yield* new SurrealDBError({
+              message: `Invalid orderDir value: ${describeInvalidValue(rawOrderDir)}`,
+            })
+          }
+          const orderDir = rawOrderDir ?? 'ASC'
+          const limit = options?.limit
+          const offset = options?.offset
+          const vars: Record<string, unknown> = self.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 = yield* self.query<unknown>(new BoundQuery(sql, vars))
+          return rows.map((row) => self.parseSchema(schema, row))
+        }
 
-  private describeInvalidValue(value: unknown): string {
-    if (typeof value === 'string') {
-      return value
-    }
+        const client = yield* self.ensureConnectedEffect(`SELECT * FROM ${table}`)
+        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)
+        }
 
-    try {
-      const serialized = JSON.stringify(value)
-      if (typeof serialized === 'string') {
-        return serialized
-      }
-      return Object.prototype.toString.call(value)
-    } catch {
-      return Object.prototype.toString.call(value)
-    }
+        const rows = yield* Effect.tryPromise({
+          try: () => query,
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to run findMany query for ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        return rows.map((row) => self.parseSchema(schema, row))
+      }),
+    )
   }
 
-  async create<T extends z.ZodTypeAny>(
+  create<T extends z.ZodTypeAny>(
     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()
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const keys = Object.keys(data)
+        if (keys.length === 0) {
+          return yield* new SurrealDBError({ message: `Cannot create record in ${table} with empty data` })
+        }
 
-    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
+        const client = yield* self.ensureConnectedEffect(`CREATE ${table}`)
+        const created = yield* Effect.tryPromise({
+          try: () => client.create<unknown>(new Table(table)).content(self.normalizeMutationData(data)).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to create record in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        const first = Array.isArray(created) ? created.at(0) : created
 
-      if (!first) {
-        throw new SurrealDBError(`Failed to create record in ${table}`)
-      }
+        if (!first) {
+          return yield* new SurrealDBError({ message: `Failed to create record in ${table}` })
+        }
 
-      return this.parseSchema(schema, first)
-    } catch (error) {
-      return this.toSurrealError(error, `CREATE ${table}`)
-    }
+        return self.parseSchema(schema, first)
+      }),
+    )
   }
 
-  async createWithId<T extends z.ZodTypeAny>(
+  createWithId<T extends z.ZodTypeAny>(
     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()
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const recordId = self.normalizeRecordId(id, table)
+        const keys = Object.keys(data)
+        if (keys.length === 0) {
+          return yield* new SurrealDBError({ message: `Cannot create record in ${table} with empty data` })
+        }
 
-    try {
-      const created = await client.create<unknown>(recordId).content(this.normalizeMutationData(data)).output('after')
-      return this.parseSchema(schema, created)
-    } catch (error) {
-      return this.toSurrealError(error, `CREATE ${recordId.toString()}`)
-    }
+        const client = yield* self.ensureConnectedEffect(`CREATE ${recordId.toString()}`)
+        const created = yield* Effect.tryPromise({
+          try: () => client.create<unknown>(recordId).content(self.normalizeMutationData(data)).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to create record in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        return self.parseSchema(schema, created)
+      }),
+    )
   }
 
-  async update<T extends z.ZodTypeAny>(
+  update<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
     schema: T,
     options?: { mutation?: RecordMutation },
-  ): 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'
+  ): AwaitableEffect<z.infer<T> | null, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const recordId = self.normalizeRecordId(id, table)
+        const keys = Object.keys(data)
+        if (keys.length === 0) {
+          return yield* new SurrealDBError({ message: 'Cannot update record with empty data' })
+        }
 
-    try {
-      const builder = client.update<unknown>(recordId)
-      const configured = configureMutation(builder, mutation, this.normalizeMutationData(data))
-      const updated = await configured.output('after')
-      return updated ? this.parseSchema(schema, updated) : null
-    } catch (error) {
-      return this.toSurrealError(error, `UPDATE ${recordId.toString()}`)
-    }
+        const mutation = options?.mutation ?? 'merge'
+        const client = yield* self.ensureConnectedEffect(`UPDATE ${recordId.toString()}`)
+        const builder = client.update<unknown>(recordId)
+        const updated: Record<string, unknown> | null | undefined = yield* Effect.tryPromise({
+          try: () => configureMutation(builder, mutation, self.normalizeMutationData(data)).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to update record in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        return self.parseOptionalSchema(schema, updated)
+      }),
+    )
   }
 
-  async upsert<T extends z.ZodTypeAny>(
+  upsert<T extends z.ZodTypeAny>(
     table: DatabaseTable,
     id: unknown,
     data: Record<string, unknown>,
     schema: T,
     options?: { mutation?: RecordMutation },
-  ): 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'
+  ): AwaitableEffect<z.infer<T>, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const recordId = self.normalizeRecordId(id, table)
+        const keys = Object.keys(data)
+        if (keys.length === 0) {
+          return yield* new SurrealDBError({ message: 'Cannot upsert record with empty data' })
+        }
 
-    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 this.parseSchema(schema, upserted)
-    } catch (error) {
-      return this.toSurrealError(error, `UPSERT ${recordId.toString()}`)
-    }
+        const mutation = options?.mutation ?? 'merge'
+        const client = yield* self.ensureConnectedEffect(`UPSERT ${recordId.toString()}`)
+        const builder = client.upsert<unknown>(recordId)
+        const upserted: Record<string, unknown> | null | undefined = yield* Effect.tryPromise({
+          try: () => configureMutation(builder, mutation, self.normalizeMutationData(data)).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to upsert record in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        const parsed = self.parseOptionalSchema(schema, upserted)
+        if (parsed === null) {
+          return yield* new SurrealDBError({ message: `Failed to upsert record in ${table}` })
+        }
+        return parsed
+      }),
+    )
   }
 
-  async deleteById(table: DatabaseTable, id: unknown): Promise<boolean> {
-    const recordId = this.normalizeRecordId(id, table)
-
-    try {
-      const result = await this.query<unknown>(new BoundQuery(`DELETE $recordId RETURN BEFORE`, { recordId }))
-      return result.length > 0
-    } catch (error) {
-      if (error instanceof Error && error.message.includes('does not exist')) {
-        return false
-      }
-      return this.toSurrealError(error, `DELETE ${recordId.toString()}`)
-    }
+  deleteById(table: DatabaseTable, id: unknown): AwaitableEffect<boolean, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const recordId = self.normalizeRecordId(id, table)
+        return yield* self.query<unknown>(new BoundQuery(`DELETE $recordId RETURN BEFORE`, { recordId })).pipe(
+          Effect.map((result) => result.length > 0),
+          Effect.catchTag('SurrealDBError', (error) => {
+            if (error.message.includes('does not exist')) {
+              return Effect.succeed(false)
+            }
+
+            return Effect.fail(self.toSurrealError(error, `DELETE ${recordId.toString()}`) as SurrealDBError)
+          }),
+        )
+      }),
+    )
   }
 
-  async deleteWhere(table: DatabaseTable, filter: Record<string, unknown>): Promise<number> {
-    this.assertValidIdentifier(table, 'table name')
-    const filterKeys = Object.keys(filter)
-    if (filterKeys.length === 0) {
-      throw new SurrealDBError(`Refusing to delete all records in ${table} without a filter`)
-    }
-    const { clause, bindings } = this.buildBoundFilterClauses(filter)
-
-    try {
-      return await this.withTransaction(async (tx) => {
-        const matched = (await tx.query(new BoundQuery(`SELECT id FROM ${table} WHERE ${clause}`, bindings))) as Array<{
-          id: unknown
-        }>
-
-        if (matched.length === 0) {
-          return 0
+  deleteWhere(table: DatabaseTable, filter: Record<string, unknown>): AwaitableEffect<number, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        assertValidIdentifier(table, 'table name')
+        const filterKeys = Object.keys(filter)
+        if (filterKeys.length === 0) {
+          return yield* new SurrealDBError({ message: `Refusing to delete all records in ${table} without a filter` })
         }
-
-        for (const row of matched) {
-          await tx.delete(this.normalizeRecordId(row.id, table))
-        }
-
-        return matched.length
-      })
-    } catch (error) {
-      return this.toSurrealError(error, `DELETE ${table} WHERE ...`)
-    }
+        const { clause, bindings } = self.buildBoundFilterClauses(filter)
+        return yield* self.withTransaction((tx) =>
+          Effect.gen(function* () {
+            const matchedRows = (yield* tx.query(
+              new BoundQuery(`SELECT id FROM ${table} WHERE ${clause}`, bindings),
+            )) as Array<{ id: unknown }>
+
+            if (matchedRows.length === 0) {
+              return 0
+            }
+
+            for (const row of matchedRows) {
+              yield* tx.delete(self.normalizeRecordId(row.id, table))
+            }
+
+            return matchedRows.length
+          }),
+        )
+      }),
+    )
   }
 
-  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()
+  updateWhere(
+    table: DatabaseTable,
+    where: ExprLike,
+    data: Record<string, unknown>,
+  ): AwaitableEffect<number, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        if (!where) {
+          return yield* new SurrealDBError({ message: `Refusing to update records in ${table} without a where clause` })
+        }
+        const keys = Object.keys(data)
+        if (keys.length === 0) {
+          return yield* new SurrealDBError({ message: `Cannot update records in ${table} with empty data` })
+        }
 
-    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) {
-      return this.toSurrealError(error, `UPDATE ${table} WHERE ...`)
-    }
+        const client = yield* self.ensureConnectedEffect(`UPDATE ${table} WHERE ...`)
+        const updated = yield* Effect.tryPromise({
+          try: () =>
+            client
+              .update<unknown>(new Table(table))
+              .where(where)
+              .merge(self.normalizeMutationData(data))
+              .output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to update records in ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        return Array.isArray(updated) ? updated.length : 1
+      }),
+    )
   }
 
-  async insert<T extends Record<string, unknown>>(
+  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) {
-      return this.toSurrealError(error, `INSERT ${table}`)
-    }
+  ): AwaitableEffect<T[], SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const client = yield* self.ensureConnectedEffect(`INSERT ${table}`)
+        const normalized = Array.isArray(data)
+          ? data.map((item) => self.normalizeMutationData(item as Record<string, unknown>))
+          : self.normalizeMutationData(data as Record<string, unknown>)
+        const inserted = yield* Effect.tryPromise({
+          try: () => client.insert<T>(new Table(table), normalized as Values<T> | Array<Values<T>>).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to insert rows into ${table}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })
+        return inserted as T[]
+      }),
+    )
   }
 
-  async relate<T extends Record<string, unknown>>(
+  relate<T extends Record<string, unknown>>(
     from: RecordIdInput,
     edgeTable: DatabaseTable,
     to: RecordIdInput,
     data?: Values<T>,
-  ): Promise<T | null> {
-    const client = await this.ensureConnected()
+  ): AwaitableEffect<T | null, SurrealDBError> {
     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) {
-      return 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) {
-      return 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)
-          }`,
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const client = yield* self.ensureConnectedEffect(
+          `RELATE ${fromRef.toString()}->${edgeTable}->${toRef.toString()}`,
         )
-      }
-      throw error
-    }
+        const normalizedData = data
+          ? (self.normalizeMutationData(data as Record<string, unknown>) as Values<T>)
+          : undefined
+        const related = (yield* Effect.tryPromise({
+          try: () => client.relate<T>(fromRef, new Table(edgeTable), toRef, normalizedData).output('after'),
+          catch: (error) =>
+            new SurrealDBError({
+              message: `Failed to relate records ${fromRef.toString()} -> ${edgeTable} -> ${toRef.toString()}: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        })) as T | T[] | null
+        if (related === null) {
+          return null
+        }
+        if (Array.isArray(related)) {
+          return related.at(0) ?? null
+        }
+        return related
+      }),
+    )
   }
-}
 
-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')
+  beginTransaction(): AwaitableEffect<DatabaseTransaction, SurrealDBError> {
+    const self = this
+    return toAwaitableEffect(
+      Effect.gen(function* () {
+        const client = yield* self.ensureConnectedEffect('BEGIN TRANSACTION')
+        const tx = yield* Effect.tryPromise({
+          try: () => client.beginTransaction(),
+          catch: (error) =>
+            new SurrealDBError({ message: `Failed to begin transaction: ${getErrorMessage(error)}`, cause: error }),
+        })
+        return self.wrapTransaction(tx)
+      }),
+    )
   }
 
-  return currentDatabaseService
-}
-
-export const databaseService = new Proxy({} as SurrealDBService, {
-  get(_target, property) {
-    if (databaseServiceOverrides.has(property)) {
-      return databaseServiceOverrides.get(property)
-    }
-
-    const resolved = resolveConfiguredDatabaseService()
-    const value: unknown = Reflect.get(resolved, property)
-    if (typeof value === 'function') {
-      // SurrealDB SDK type gap — Reflect.get returns unknown, but we know the resolved target shape
-      return bindTargetMethod(
-        resolved as unknown as Record<PropertyKey, unknown>,
-        value as (...args: unknown[]) => unknown,
+  withTransaction<T, E, R>(
+    work: (tx: DatabaseTransaction) => Effect.Effect<T, E, R>,
+  ): Effect.Effect<T, SurrealDBError | E, R> {
+    const self = this
+    return Effect.gen(function* () {
+      const tx = yield* self.beginTransaction()
+      const cancelEffect = tx.cancel().pipe(
+        Effect.catch((cancelError: SurrealDBError) =>
+          Effect.sync(() => {
+            self.logger?.warn?.(`Failed to cancel transaction after error: ${cancelError.message}`)
+          }),
+        ),
+        Effect.asVoid,
       )
-    }
 
-    return value
-  },
-  set(_target, property, value) {
-    databaseServiceOverrides.set(property, value)
-    return true
-  },
-})
-
-export function setDatabaseService(db: SurrealDBService): void {
-  if (db === databaseService) {
-    return
+      return yield* Effect.gen(function* () {
+        const result = yield* work(tx)
+        yield* tx.commit()
+        return result
+      }).pipe(Effect.onError(() => cancelEffect))
+    })
   }
-
-  currentDatabaseService = db
 }