@lota-sdk/core 0.4.8 → 0.4.10

package/src/db/startup.ts

@@ -1,9 +1,14 @@
 import { recordIdSchema } from '@lota-sdk/shared'
+import { Duration, Effect, Match, 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
-
-    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)
-    }
-  }
 
-  params.logger?.error?.(`Timed out waiting for ${params.label}: ${getErrorMessage(lastError)}`)
-  throw lastError instanceof Error ? lastError : new Error(`Timed out waiting for ${params.label}`)
+  const connectEffect = effectTryPromise(
+    () => params.connect(),
+    (error) => new DatabaseError({ message: `Waiting for ${params.label}: ${getErrorMessage(error)}`, cause: error }),
+  )
+
+  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,
+      })
+    }),
+  )
 }
 
-async function readDatabaseBootstrapRecord(
+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))
+}
+
+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,135 @@ 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)
-  }
+  const logFailure = Match.type<BootstrapWaitFailure>().pipe(
+    Match.tag('schema-not-ready', (failure) => {
+      params.logger?.info?.(
+        `Waiting for ${params.label} schema readiness (${attempt}, expected=${expectedFingerprint}, current=${failure.currentFingerprint})`,
+      )
+    }),
+    Match.tag('read-failed', (failure) => {
+      params.logger?.warn?.(
+        `Waiting for ${params.label} schema readiness (${attempt}): ${getErrorMessage(failure.cause)}`,
+      )
+    }),
+    Match.exhaustive,
+  )
 
-  if (lastError instanceof Error) {
-    throw lastError
-  }
+  const toTimeoutError = Match.type<BootstrapWaitFailure>().pipe(
+    Match.tag(
+      'schema-not-ready',
+      () => new DatabaseError({ message: `Timed out waiting for ${params.label} schema readiness` }),
+    ),
+    Match.tag(
+      'read-failed',
+      (failure) =>
+        new DatabaseError({ message: `Timed out waiting for ${params.label} schema readiness`, cause: failure.cause }),
+    ),
+    Match.exhaustive,
+  )
 
-  throw new Error(`Timed out waiting for ${params.label} schema readiness`)
+  return waitForExpectedFingerprint.pipe(
+    Effect.tapError((failure) =>
+      Effect.sync(() => {
+        attempt++
+        if (!shouldLogRetry(attempt)) return
+        logFailure(failure)
+      }),
+    ),
+    Effect.retry({
+      times: Math.max(0, Math.ceil(maxWaitMs / retryDelayMs) - 1),
+      schedule: Schedule.fixed(Duration.millis(retryDelayMs)),
+    }),
+    Effect.mapError(toTimeoutError),
+  )
 }
 
-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,96 @@
+import { Effect } from 'effect'
+
+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> }
+
+type Callable = (...args: Array<unknown>) => unknown
+
+function isCallable(value: unknown): value is Callable {
+  return typeof value === 'function'
+}
+
+function isRuntimeEffect(value: unknown): value is Effect.Effect<unknown, never, never> {
+  return Effect.isEffect(value)
+}
+
+/**
+ * Wraps an Effect so it can be `await`-ed as if it were a Promise, while still
+ * passing `Effect.isEffect` checks and exposing the underlying Effect properties.
+ *
+ * Implementation: returns a `Proxy` around the Effect that only intercepts the
+ * PromiseLike methods (`then`/`catch`/`finally`) plus `Symbol.toStringTag`. The
+ * Promise is created lazily on first `await` and cached for the wrapper's
+ * lifetime so repeated awaits share a result. The original Effect object is
+ * never mutated.
+ */
+export function toAwaitableEffect<A, E>(
+  effect: Effect.Effect<A, E, never>,
+  options?: AwaitableEffectOptions,
+): AwaitableEffect<A, E> {
+  const runPromise = options?.runPromise ?? Effect.runPromise
+  let cachedPromise: Promise<A> | undefined
+  const getPromise = (): Promise<A> => (cachedPromise ??= runPromise(effect))
+
+  const then: Promise<A>['then'] = (onFulfilled, onRejected) => getPromise().then(onFulfilled, onRejected)
+  const catchMethod: Promise<A>['catch'] = (onRejected) => getPromise().catch(onRejected)
+  const finallyMethod: Promise<A>['finally'] = (onFinally) => getPromise().finally(onFinally)
+
+  return new Proxy(effect as object, {
+    get(target, property, receiver) {
+      if (property === 'then') return then
+      if (property === 'catch') return catchMethod
+      if (property === 'finally') return finallyMethod
+      if (property === Symbol.toStringTag) return 'Promise'
+      return Reflect.get(target, property, receiver) as unknown
+    },
+  }) as AwaitableEffect<A, E>
+}
+
+/**
+ * Returns a proxy over a service whose Effect-returning methods are
+ * transparently wrapped with `toAwaitableEffect`. Non-Effect return values
+ * pass through untouched.
+ */
+export function toAwaitableService<T extends object>(
+  service: T,
+  options?: AwaitableEffectOptions,
+): AwaitableService<T> {
+  const wrappedMethods = new Map<PropertyKey, Callable>()
+
+  return new Proxy(service, {
+    get(target, property, receiver) {
+      const value = Reflect.get(target, property, receiver)
+      if (!isCallable(value)) {
+        return value
+      }
+
+      const existing = wrappedMethods.get(property)
+      if (existing) {
+        return existing
+      }
+
+      const wrapped: Callable = (...args) => {
+        const result = value.apply(target, args)
+        return isRuntimeEffect(result) ? toAwaitableEffect(result, 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,123 @@
+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>)
+
+function invokePromiseEffectEvaluator<A, E, R>(
+  evaluate: PromiseEffectEvaluator<A, E, R>,
+): PromiseLike<A> | Effect.Effect<A, E, R> {
+  return (evaluate as () => 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 = invokePromiseEffectEvaluator(evaluate)
+      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, E = never, R = never>(
+  evaluate: PromiseEffectEvaluator<A, E, R>,
+  message: string,
+): Effect.Effect<A, ServiceError, R> {
+  return Effect.suspend(() => {
+    try {
+      const value = invokePromiseEffectEvaluator(evaluate)
+      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 makeEffectTryPromiseWithOperation<E>(
+  onError: (operation: string, message: string, cause: unknown) => E,
+) {
+  return <A, E1 = never, R = never>(
+    operation: string,
+    message: string,
+    evaluate: PromiseEffectEvaluator<A, E1, R>,
+  ): Effect.Effect<A, E, R> => effectTryPromise(evaluate, (cause) => onError(operation, 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))
+    }
+  })
+}
+
+export function iterateEffect<A, E, R>(
+  initial: A,
+  options: { while: (state: A) => boolean; body: (state: A) => Effect.Effect<A, E, R> },
+): Effect.Effect<A, E, R> {
+  const step = (state: A): Effect.Effect<A, E, R> =>
+    options.while(state) ? options.body(state).pipe(Effect.flatMap(step)) : Effect.succeed(state)
+  return Effect.suspend(() => step(initial))
+}

package/src/effect/index.ts

@@ -0,0 +1,24 @@
+export * from './awaitable-effect'
+export * from './helpers'
+export * from './layers'
+export * from './runtime'
+export * from './services'
+export * from './zod'
+export {
+  ActiveThreadRunConflictError,
+  AiGenerationError,
+  BaseServicePersistenceError,
+  ConfigurationError,
+  ConflictError,
+  DatabaseError,
+  ForbiddenError,
+  LockAcquisitionError,
+  LockLostError,
+  RedisError,
+  ServiceError,
+  ThreadTurnError,
+  TimeoutError,
+  ValidationError,
+  isEffectError,
+} from './errors'
+export type { EffectError, ValidationIssue } from './errors'