@lota-sdk/core 0.4.7 → 0.4.9

package/src/db/startup.ts

@@ -1,9 +1,14 @@
 import { recordIdSchema } from '@lota-sdk/shared'
+import { Duration, Effect, Schedule } from 'effect'
 import { BoundQuery, RecordId } from 'surrealdb'
 import { z } from 'zod'
 
+import { DatabaseError } from '../effect/errors'
+import { effectTryPromise } from '../effect/helpers'
+import { nowDate } from '../utils/date-time'
 import { getErrorMessage } from '../utils/errors'
 import type { SurrealDBService, SurrealDatabaseLogger } from './service'
+import type { SurrealDBError } from './service-normalization'
 import { TABLES } from './tables'
 
 const DATABASE_BOOTSTRAP_KEY = 'database-schema-ready'
@@ -21,48 +26,67 @@ const RuntimeBootstrapRecordSchema = z.object({
 
 type StartupLogger = Pick<SurrealDatabaseLogger, 'info' | 'warn' | 'error'>
 
+type BootstrapWaitFailure =
+  | { _tag: 'schema-not-ready'; currentFingerprint: string }
+  | { _tag: 'read-failed'; cause: unknown }
+
 function shouldLogRetry(attempt: number): boolean {
   return attempt === 1 || attempt % RETRY_LOG_INTERVAL === 0
 }
 
-export async function connectWithStartupRetry(params: {
-  connect: () => Promise<void>
+function connectWithStartupRetryEffectInternal(params: {
+  connect: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
   label: string
   logger?: StartupLogger
   retryDelayMs?: number
   maxWaitMs?: number
-}): Promise<void> {
+}): Effect.Effect<void, DatabaseError> {
   const retryDelayMs = params.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
   const maxWaitMs = params.maxWaitMs ?? DEFAULT_MAX_WAIT_MS
-  const startedAt = Date.now()
 
   let attempt = 0
-  let lastError: unknown = null
 
-  while (Date.now() - startedAt <= maxWaitMs) {
-    attempt += 1
+  const connectEffect = effectTryPromise(
+    () => params.connect(),
+    (error) => new DatabaseError({ message: `Waiting for ${params.label}: ${getErrorMessage(error)}`, cause: error }),
+  )
 
-    try {
-      await params.connect()
-      return
-    } catch (error) {
-      lastError = error
-      if (shouldLogRetry(attempt)) {
-        params.logger?.warn?.(
-          `Waiting for ${params.label} (${attempt}, elapsed=${Date.now() - startedAt}ms): ${getErrorMessage(error)}`,
-        )
-      }
-      await Bun.sleep(retryDelayMs)
-    }
-  }
+  return connectEffect.pipe(
+    Effect.tapError((error) =>
+      Effect.sync(() => {
+        attempt++
+        if (shouldLogRetry(attempt)) {
+          params.logger?.warn?.(error.message)
+        }
+      }),
+    ),
+    Effect.retry({
+      times: Math.max(0, Math.ceil(maxWaitMs / retryDelayMs) - 1),
+      schedule: Schedule.fixed(Duration.millis(retryDelayMs)),
+    }),
+    Effect.mapError((error) => {
+      params.logger?.error?.(`Timed out waiting for ${params.label}: ${getErrorMessage(error)}`)
+      return new DatabaseError({
+        message: `Timed out waiting for ${params.label}: ${getErrorMessage(error)}`,
+        cause: error,
+      })
+    }),
+  )
+}
 
-  params.logger?.error?.(`Timed out waiting for ${params.label}: ${getErrorMessage(lastError)}`)
-  throw lastError instanceof Error ? lastError : new Error(`Timed out waiting for ${params.label}`)
+export function connectWithStartupRetry(params: {
+  connect: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  label: string
+  logger?: StartupLogger
+  retryDelayMs?: number
+  maxWaitMs?: number
+}): Promise<void> {
+  return Effect.runPromise(connectWithStartupRetryEffectInternal(params))
 }
 
-async function readDatabaseBootstrapRecord(
+function readDatabaseBootstrapRecord(
   databaseService: SurrealDBService,
-): Promise<z.infer<typeof RuntimeBootstrapRecordSchema> | null> {
+): Effect.Effect<z.infer<typeof RuntimeBootstrapRecordSchema> | null, SurrealDBError> {
   return databaseService.queryOne(
     new BoundQuery(
       `SELECT *
@@ -75,74 +99,124 @@ async function readDatabaseBootstrapRecord(
   )
 }
 
-export async function waitForDatabaseBootstrap(params: {
+function waitForDatabaseBootstrapEffectInternal(params: {
   databaseService: SurrealDBService
   expectedFingerprint?: string | null
   label: string
   logger?: StartupLogger
-  connect?: () => Promise<void>
+  connect?: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
   retryDelayMs?: number
   maxWaitMs?: number
-}): Promise<void> {
+}): Effect.Effect<void, DatabaseError> {
   const expectedFingerprint = params.expectedFingerprint?.trim()
   if (!expectedFingerprint) {
-    return
+    return Effect.void
   }
 
   const retryDelayMs = params.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
   const maxWaitMs = params.maxWaitMs ?? DEFAULT_MAX_WAIT_MS
-  const startedAt = Date.now()
-
   let attempt = 0
-  let lastError: unknown = null
 
-  while (Date.now() - startedAt <= maxWaitMs) {
-    attempt += 1
+  const readBootstrapRecord = Effect.gen(function* () {
+    const connect = params.connect
+    if (connect) {
+      yield* effectTryPromise(
+        () => connect(),
+        (error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error }),
+      )
+    }
 
-    try {
-      if (params.connect) {
-        await params.connect()
-      }
+    return yield* effectTryPromise(
+      () => readDatabaseBootstrapRecord(params.databaseService),
+      (error): BootstrapWaitFailure => ({ _tag: 'read-failed', cause: error }),
+    )
+  })
 
-      const record = await readDatabaseBootstrapRecord(params.databaseService)
+  const waitForExpectedFingerprint = readBootstrapRecord.pipe(
+    Effect.flatMap((record) => {
       if (record?.schemaFingerprint === expectedFingerprint) {
-        return
+        return Effect.void
       }
 
-      if (shouldLogRetry(attempt)) {
-        const currentFingerprint =
-          typeof record?.schemaFingerprint === 'string' && record.schemaFingerprint.length > 0
-            ? record.schemaFingerprint
-            : 'missing'
-        params.logger?.info?.(
-          `Waiting for ${params.label} schema readiness (${attempt}, expected=${expectedFingerprint}, current=${currentFingerprint})`,
-        )
-      }
-    } catch (error) {
-      lastError = error
-      if (shouldLogRetry(attempt)) {
-        params.logger?.warn?.(`Waiting for ${params.label} schema readiness (${attempt}): ${getErrorMessage(error)}`)
-      }
-    }
+      const currentFingerprint =
+        typeof record?.schemaFingerprint === 'string' && record.schemaFingerprint.length > 0
+          ? record.schemaFingerprint
+          : 'missing'
+      return Effect.fail<BootstrapWaitFailure>({ _tag: 'schema-not-ready', currentFingerprint })
+    }),
+  )
 
-    await Bun.sleep(retryDelayMs)
-  }
+  return waitForExpectedFingerprint.pipe(
+    Effect.tapError((failure) =>
+      Effect.sync(() => {
+        attempt++
+        if (!shouldLogRetry(attempt)) return
 
-  if (lastError instanceof Error) {
-    throw lastError
-  }
+        if (failure._tag === 'schema-not-ready') {
+          params.logger?.info?.(
+            `Waiting for ${params.label} schema readiness (${attempt}, expected=${expectedFingerprint}, current=${failure.currentFingerprint})`,
+          )
+          return
+        }
 
-  throw new Error(`Timed out waiting for ${params.label} schema readiness`)
+        params.logger?.warn?.(
+          `Waiting for ${params.label} schema readiness (${attempt}): ${getErrorMessage(failure.cause)}`,
+        )
+      }),
+    ),
+    Effect.retry({
+      times: Math.max(0, Math.ceil(maxWaitMs / retryDelayMs) - 1),
+      schedule: Schedule.fixed(Duration.millis(retryDelayMs)),
+    }),
+    Effect.mapError(
+      (failure) =>
+        new DatabaseError({
+          message: `Timed out waiting for ${params.label} schema readiness`,
+          ...(failure._tag === 'read-failed' ? { cause: failure.cause } : {}),
+        }),
+    ),
+  )
 }
 
-export async function publishDatabaseBootstrap(params: {
+export function waitForDatabaseBootstrap(params: {
+  databaseService: SurrealDBService
+  expectedFingerprint?: string | null
+  label: string
+  logger?: StartupLogger
+  connect?: () => PromiseLike<void> | Effect.Effect<void, SurrealDBError>
+  retryDelayMs?: number
+  maxWaitMs?: number
+}): Promise<void> {
+  return Effect.runPromise(waitForDatabaseBootstrapEffectInternal(params))
+}
+
+export function publishDatabaseBootstrap(params: {
   databaseService: SurrealDBService
   schemaFingerprint: string
 }): Promise<void> {
-  await params.databaseService.upsert(
-    TABLES.RUNTIME_BOOTSTRAP,
-    new RecordId(TABLES.RUNTIME_BOOTSTRAP, DATABASE_BOOTSTRAP_KEY),
-    { key: DATABASE_BOOTSTRAP_KEY, schemaFingerprint: params.schemaFingerprint, readyAt: new Date() },
-    RuntimeBootstrapRecordSchema,
+  return Effect.runPromise(publishDatabaseBootstrapEffect(params))
+}
+
+export function publishDatabaseBootstrapEffect(params: {
+  databaseService: SurrealDBService
+  schemaFingerprint: string
+}): Effect.Effect<void, DatabaseError> {
+  return Effect.asVoid(
+    params.databaseService
+      .upsert(
+        TABLES.RUNTIME_BOOTSTRAP,
+        new RecordId(TABLES.RUNTIME_BOOTSTRAP, DATABASE_BOOTSTRAP_KEY),
+        { key: DATABASE_BOOTSTRAP_KEY, schemaFingerprint: params.schemaFingerprint, readyAt: nowDate() },
+        RuntimeBootstrapRecordSchema,
+      )
+      .pipe(
+        Effect.mapError(
+          (error) =>
+            new DatabaseError({
+              message: `Failed to publish database bootstrap: ${getErrorMessage(error)}`,
+              cause: error,
+            }),
+        ),
+      ),
   )
 }

package/src/db/transaction-conflict.ts

@@ -0,0 +1,15 @@
+export function isRetriableTransactionConflict(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')
+  )
+}

package/src/effect/awaitable-effect.ts

@@ -0,0 +1,87 @@
+import { Effect } from 'effect'
+
+const awaitableEffectMarker = Symbol('AwaitableEffect')
+
+type AwaitableEffectState<A> = { promise?: Promise<A> }
+
+export type AwaitableEffect<A, E> = Effect.Effect<A, E, never> & Promise<A>
+
+export type AwaitableValue<T> = T extends (...args: infer TArgs) => Effect.Effect<infer A, infer E, never>
+  ? (...args: TArgs) => AwaitableEffect<A, E>
+  : T extends (...args: infer TArgs) => infer TResult
+    ? (...args: TArgs) => TResult
+    : T
+
+type AwaitableServiceMethods<T> = {
+  [K in keyof T]: AwaitableValue<T[K]>
+}
+
+export type AwaitableService<T> = AwaitableServiceMethods<T>
+
+export type MaybeAwaitableService<T extends object> = T | AwaitableService<T>
+
+type AwaitableEffectOptions = { runPromise?: <A, E>(effect: Effect.Effect<A, E, never>) => Promise<A> }
+
+export function toAwaitableEffect<A, E>(
+  effect: Effect.Effect<A, E, never>,
+  options?: AwaitableEffectOptions,
+): AwaitableEffect<A, E> {
+  const existing = effect as AwaitableEffect<A, E> & { [awaitableEffectMarker]?: AwaitableEffectState<A> }
+
+  if (existing[awaitableEffectMarker]) {
+    return existing
+  }
+
+  const state: AwaitableEffectState<A> = {}
+  const runPromise = options?.runPromise ?? Effect.runPromise
+  const ensurePromise = () => (state.promise ??= runPromise(effect))
+  const candidate = Object.create(
+    Object.getPrototypeOf(effect),
+    Object.getOwnPropertyDescriptors(effect),
+  ) as AwaitableEffect<A, E> & { [awaitableEffectMarker]?: AwaitableEffectState<A> }
+
+  const then: Promise<A>['then'] = (onfulfilled, onrejected) => ensurePromise().then(onfulfilled, onrejected)
+  const catchMethod: Promise<A>['catch'] = (onrejected) => ensurePromise().catch(onrejected)
+  const finallyMethod: Promise<A>['finally'] = (onfinally) => ensurePromise().finally(onfinally)
+
+  void Object.defineProperties(candidate, {
+    then: { value: then, configurable: true },
+    catch: { value: catchMethod, configurable: true },
+    finally: { value: finallyMethod, configurable: true },
+    [Symbol.toStringTag]: { value: 'Promise', configurable: true },
+    [awaitableEffectMarker]: { value: state },
+  })
+
+  return candidate
+}
+
+export function toAwaitableService<T extends object>(
+  service: T,
+  options?: AwaitableEffectOptions,
+): AwaitableService<T> {
+  const wrappedMethods = new Map<PropertyKey, unknown>()
+
+  return new Proxy(service, {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver)
+      if (typeof value !== 'function') {
+        return value
+      }
+
+      const existing = wrappedMethods.get(property)
+      if (existing !== undefined) {
+        return existing
+      }
+
+      const wrapped = (...args: unknown[]) => {
+        const result = Reflect.apply(value, target, args)
+        return Effect.isEffect(result)
+          ? toAwaitableEffect(result as Effect.Effect<unknown, unknown, never>, options)
+          : result
+      }
+
+      wrappedMethods.set(property, wrapped)
+      return wrapped
+    },
+  }) as AwaitableService<T>
+}

package/src/effect/errors.ts

@@ -0,0 +1,121 @@
+import { Schema } from 'effect'
+
+const ValidationIssueSchema = Schema.Struct({ path: Schema.String, message: Schema.String })
+
+export type ValidationIssue = typeof ValidationIssueSchema.Type
+
+export class DatabaseError extends Schema.TaggedErrorClass<DatabaseError>()('DatabaseError', {
+  message: Schema.String,
+  query: Schema.optional(Schema.String),
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export class ServiceError extends Schema.TaggedErrorClass<ServiceError>()('ServiceError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export class BaseServicePersistenceError extends Schema.TaggedErrorClass<BaseServicePersistenceError>()(
+  'BaseServicePersistenceError',
+  { message: Schema.String, cause: Schema.Defect },
+) {}
+
+export class RedisError extends Schema.TaggedErrorClass<RedisError>()('RedisError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+export class TimeoutError extends Schema.TaggedErrorClass<TimeoutError>()('TimeoutError', {
+  operation: Schema.String,
+  ms: Schema.Number,
+}) {}
+
+export class LockAcquisitionError extends Schema.TaggedErrorClass<LockAcquisitionError>()('LockAcquisitionError', {
+  lockKey: Schema.String,
+  maxWaitMs: Schema.Number,
+}) {}
+
+export class LockLostError extends Schema.TaggedErrorClass<LockLostError>()('LockLostError', {
+  lockKey: Schema.String,
+}) {}
+
+export class NotFoundError extends Schema.TaggedErrorClass<NotFoundError>()('NotFoundError', {
+  resource: Schema.String,
+  id: Schema.optional(Schema.String),
+  message: Schema.String,
+}) {}
+
+export class BadRequestError extends Schema.TaggedErrorClass<BadRequestError>()('BadRequestError', {
+  message: Schema.String,
+}) {}
+
+export class ConflictError extends Schema.TaggedErrorClass<ConflictError>()('ConflictError', {
+  message: Schema.String,
+}) {}
+
+export class ForbiddenError extends Schema.TaggedErrorClass<ForbiddenError>()('ForbiddenError', {
+  message: Schema.String,
+}) {}
+
+export class ValidationError extends Schema.TaggedErrorClass<ValidationError>()('ValidationError', {
+  message: Schema.String,
+  issues: Schema.optional(Schema.Array(ValidationIssueSchema)),
+}) {}
+
+export class AiGenerationError extends Schema.TaggedErrorClass<AiGenerationError>()('AiGenerationError', {
+  message: Schema.String,
+  source: Schema.String,
+  status: Schema.optional(Schema.Number),
+  rateLimited: Schema.optional(Schema.Boolean),
+  retryAfter: Schema.optional(Schema.String),
+  providerData: Schema.optional(Schema.String),
+  responseBody: Schema.optional(Schema.String),
+  url: Schema.optional(Schema.String),
+}) {}
+
+export class ThreadTurnError extends Schema.TaggedErrorClass<ThreadTurnError>()('ThreadTurnError', {
+  message: Schema.String,
+  reason: Schema.Literals(['bad-request', 'conflict']),
+}) {}
+
+export class ActiveThreadRunConflictError extends Schema.TaggedErrorClass<ActiveThreadRunConflictError>()(
+  'ActiveThreadRunConflictError',
+  { threadId: Schema.String, activeRunId: Schema.String, message: Schema.String },
+) {}
+
+export class ConfigurationError extends Schema.TaggedErrorClass<ConfigurationError>()('ConfigurationError', {
+  message: Schema.String,
+  key: Schema.optional(Schema.String),
+}) {}
+
+const EFFECT_ERROR_CLASSES = [
+  ActiveThreadRunConflictError,
+  AiGenerationError,
+  BadRequestError,
+  BaseServicePersistenceError,
+  ConfigurationError,
+  ConflictError,
+  DatabaseError,
+  ForbiddenError,
+  LockAcquisitionError,
+  LockLostError,
+  NotFoundError,
+  RedisError,
+  ServiceError,
+  ThreadTurnError,
+  TimeoutError,
+  ValidationError,
+] as const
+
+export type EffectError = InstanceType<(typeof EFFECT_ERROR_CLASSES)[number]>
+
+const EFFECT_ERROR_TAGS = new Set(EFFECT_ERROR_CLASSES.map((cls) => cls.name))
+
+export function isEffectError(error: unknown): error is EffectError {
+  if (!error || typeof error !== 'object') {
+    return false
+  }
+
+  const tag = (error as { _tag?: unknown })._tag
+  return typeof tag === 'string' && EFFECT_ERROR_TAGS.has(tag)
+}

package/src/effect/helpers.ts

@@ -0,0 +1,98 @@
+import { Cause, Effect } from 'effect'
+
+import { ServiceError } from './errors'
+
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  if (typeof value !== 'object' && typeof value !== 'function') {
+    return false
+  }
+
+  if (value === null) {
+    return false
+  }
+
+  return 'then' in value && typeof value.then === 'function'
+}
+
+type PromiseEffectEvaluator<A, E = never, R = never> =
+  | (() => PromiseLike<A> | Effect.Effect<A, E, R>)
+  | ((signal: AbortSignal) => PromiseLike<A> | Effect.Effect<A, E, R>)
+
+export function effectTryPromise<A, E = never, R = never>(
+  evaluate: PromiseEffectEvaluator<A, E, R>,
+): Effect.Effect<A, Cause.UnknownError, R>
+export function effectTryPromise<A, E1, E2, R>(
+  evaluate: PromiseEffectEvaluator<A, E1, R>,
+  onError: (cause: unknown) => E2,
+): Effect.Effect<A, E2, R>
+export function effectTryPromise<A, E1, E2, R>(
+  evaluate: PromiseEffectEvaluator<A, E1, R>,
+  onError?: (cause: unknown) => E2,
+): Effect.Effect<A, E2 | Cause.UnknownError, R> {
+  return Effect.suspend(() => {
+    try {
+      const value = (evaluate as () => PromiseLike<A> | Effect.Effect<A, E1, R>)()
+      if (Effect.isEffect(value)) {
+        if (onError) {
+          return value.pipe(Effect.mapError((cause) => onError(cause)))
+        }
+
+        return value.pipe(Effect.mapError((cause) => new Cause.UnknownError(cause)))
+      }
+
+      return onError
+        ? Effect.tryPromise({ try: () => value, catch: onError })
+        : Effect.tryPromise({ try: () => value, catch: (cause) => new Cause.UnknownError(cause) })
+    } catch (cause) {
+      return Effect.fail(onError ? onError(cause) : new Cause.UnknownError(cause))
+    }
+  })
+}
+
+export function effectTryServicePromise<A>(
+  evaluate: PromiseEffectEvaluator<A, unknown, never>,
+  message: string,
+): Effect.Effect<A, ServiceError, never> {
+  return Effect.suspend(() => {
+    try {
+      const value = (evaluate as () => PromiseLike<A> | Effect.Effect<A, unknown, never>)()
+      if (Effect.isEffect(value)) {
+        return value.pipe(Effect.mapError((cause) => new ServiceError({ message, cause })))
+      }
+
+      return Effect.tryPromise({ try: () => value, catch: (cause) => new ServiceError({ message, cause }) })
+    } catch (cause) {
+      return Effect.fail(new ServiceError({ message, cause }))
+    }
+  })
+}
+
+export function makeEffectTryPromiseWithMessage<E>(onError: (message: string, cause: unknown) => E) {
+  return <A, E1 = never, R = never>(
+    evaluate: PromiseEffectEvaluator<A, E1, R>,
+    message: string,
+  ): Effect.Effect<A, E, R> => effectTryPromise(evaluate, (cause) => onError(message, cause))
+}
+
+export function effectTryMaybeAsync<A>(evaluate: () => A | PromiseLike<A>): Effect.Effect<A, Cause.UnknownError, never>
+export function effectTryMaybeAsync<A, E>(
+  evaluate: () => A | PromiseLike<A>,
+  onError: (cause: unknown) => E,
+): Effect.Effect<A, E, never>
+export function effectTryMaybeAsync<A, E>(
+  evaluate: () => A | PromiseLike<A>,
+  onError?: (cause: unknown) => E,
+): Effect.Effect<A, E | Cause.UnknownError, never> {
+  return Effect.suspend(() => {
+    try {
+      const value = evaluate()
+      return isPromiseLike(value)
+        ? onError
+          ? effectTryPromise(() => value, onError)
+          : effectTryPromise(() => value)
+        : Effect.succeed(value)
+    } catch (cause) {
+      return Effect.fail(onError ? onError(cause) : new Cause.UnknownError(cause))
+    }
+  })
+}

package/src/effect/index.ts

@@ -0,0 +1,22 @@
+export * from './awaitable-effect'
+export * from './helpers'
+export * from './layers'
+export * from './runtime'
+export * from './services'
+export * from './zod'
+export {
+  ActiveThreadRunConflictError,
+  ConfigurationError,
+  ConflictError,
+  DatabaseError,
+  LockAcquisitionError,
+  LockLostError,
+  RedisError,
+  isEffectError,
+  ThreadTurnError as EffectThreadTurnError,
+  TimeoutError,
+  ValidationError as EffectValidationError,
+  BadRequestError as EffectBadRequestError,
+  NotFoundError as EffectNotFoundError,
+} from './errors'
+export type { EffectError, ValidationIssue } from './errors'