@lota-sdk/core 0.4.8 → 0.4.10

package/src/queues/plan-scheduler.queue.ts

@@ -1,11 +1,18 @@
 import type { Job } from 'bullmq'
+import { Schema, Effect } from 'effect'
+import type { Context } from 'effect'
+import type IORedis from 'ioredis'
 
 import { serverLogger } from '../config/logger'
-import { databaseService } from '../db/service'
-import { planDeadlineService } from '../services/plan-deadline.service'
-import { planSchedulerService } from '../services/plan-scheduler.service'
+import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import { PlanCycleServiceTag } from '../services/plan/plan-cycle.service'
+import { PlanDeadlineServiceTag } from '../services/plan/plan-deadline.service'
+import { PlanExecutorServiceTag } from '../services/plan/plan-executor.service'
+import { PlanSchedulerServiceTag } from '../services/plan/plan-scheduler.service'
+import { nowEpochMillis } from '../utils/date-time'
 import type { WorkerHandle } from '../workers/worker-utils'
-import { createQueueFactory } from './queue-factory'
+import { createQueueFactoryWithDeps } from './queue-factory'
+import { runStandaloneQueueWorker } from './standalone-worker'
 
 export interface PlanSchedulerFireJob {
   type: 'fire-schedule'
@@ -21,50 +28,75 @@ export type PlanSchedulerJob = PlanSchedulerFireJob | PlanSchedulerDeadlineJob
 
 export const PLAN_SCHEDULER_QUEUE = 'plan-scheduler'
 
-async function processPlanSchedulerJob(job: Job<PlanSchedulerJob>): Promise<void> {
-  await databaseService.connect()
+interface PlanSchedulerQueueDeps {
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
+  planSchedulerService: Context.Service.Shape<typeof PlanSchedulerServiceTag>
+  planDeadlineService: Context.Service.Shape<typeof PlanDeadlineServiceTag>
+  planExecutorService: Context.Service.Shape<typeof PlanExecutorServiceTag>
+  planCycleService: Context.Service.Shape<typeof PlanCycleServiceTag>
+}
+
+class PlanSchedulerQueueError extends Schema.TaggedErrorClass<PlanSchedulerQueueError>()('PlanSchedulerQueueError', {
+  stage: Schema.Literals(['remove-schedule-fire-job', 'recover-active-schedules', 'recover-deadline-checks']),
+  message: Schema.String,
+  cause: Schema.Defect,
+}) {}
+
+function toPlanSchedulerQueueError(stage: PlanSchedulerQueueError['stage'], cause: unknown): PlanSchedulerQueueError {
+  return new PlanSchedulerQueueError({ stage, message: cause instanceof Error ? cause.message : String(cause), cause })
+}
 
+function processPlanSchedulerJob(deps: PlanSchedulerQueueDeps, job: Job<PlanSchedulerJob>): Promise<void> {
+  const { planSchedulerService, planDeadlineService, planExecutorService, planCycleService } = deps
   switch (job.data.type) {
     case 'fire-schedule':
-      await planSchedulerService.fireScheduleById(job.data.scheduleId)
-      break
+      return Effect.runPromise(
+        Effect.asVoid(
+          planSchedulerService.fireScheduleById(job.data.scheduleId, {
+            promoteDelayedNode: (params) => planExecutorService.promoteDelayedNode(params),
+            advanceCycle: (cycleId) => planCycleService.advanceCycle(cycleId),
+            recoverDeadlineChecks: () => Effect.runPromise(Effect.asVoid(planDeadlineService.recoverDeadlineChecks())),
+          }),
+        ),
+      )
     case 'check-deadlines':
-      await planDeadlineService.checkDeadlines()
-      break
+      return Effect.runPromise(Effect.asVoid(planDeadlineService.checkDeadlines()))
   }
 }
 
-const planScheduler = createQueueFactory<PlanSchedulerJob>({
+const planScheduler = createQueueFactoryWithDeps<PlanSchedulerJob, PlanSchedulerQueueDeps>({
   name: PLAN_SCHEDULER_QUEUE,
   displayName: 'Plan scheduler',
   jobName: 'plan-scheduler-job',
   concurrency: 1,
   defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 5000 } },
+  prepare: ({ databaseService }) => databaseService.connect(),
   processor: processPlanSchedulerJob,
 })
 
 /** Enqueue a delayed job that fires a specific schedule at its nextFireAt time. */
-export async function enqueueScheduleFire(scheduleId: string, delayMs: number): Promise<void> {
-  await planScheduler.enqueue(
+export function enqueueScheduleFire(scheduleId: string, delayMs: number): Promise<void> {
+  return planScheduler.enqueue(
     { type: 'fire-schedule', scheduleId },
     { delay: Math.max(0, delayMs), jobId: `schedule:${scheduleId}`, removeOnComplete: true, removeOnFail: 50 },
   )
 }
 
 /** Remove a pending fire job for a schedule (on cancel/pause/complete). */
-export async function removeScheduleFireJob(scheduleId: string): Promise<void> {
-  try {
-    await planScheduler.getQueue().remove(`schedule:${scheduleId}`)
-  } catch {
-    // Job may not exist (already fired or never enqueued) — safe to ignore
-  }
+export function removeScheduleFireJob(scheduleId: string): Promise<void> {
+  return Effect.runPromise(
+    Effect.tryPromise({
+      try: () => planScheduler.getQueue().remove(`schedule:${scheduleId}`),
+      catch: (cause) => toPlanSchedulerQueueError('remove-schedule-fire-job', cause),
+    }).pipe(Effect.asVoid),
+  )
 }
 
 const DEADLINE_CHECK_JOB_PREFIX = 'deadline-check'
 
-export async function enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
-  const delay = Math.max(0, scheduledFor.getTime() - Date.now())
-  await planScheduler.enqueue(
+export function enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
+  const delay = Math.max(0, scheduledFor.getTime() - nowEpochMillis())
+  return planScheduler.enqueue(
     { type: 'check-deadlines', scheduledFor: scheduledFor.toISOString() },
     {
       delay,
@@ -75,23 +107,55 @@ export async function enqueueDeadlineCheck(scheduledFor: Date): Promise<void> {
   )
 }
 
-export function startPlanSchedulerWorker(options: { registerSignals?: boolean } = {}): WorkerHandle {
-  const handle = planScheduler.startWorker(options)
+export function startPlanSchedulerWorker(options: {
+  registerSignals?: boolean
+  connectionProvider: () => IORedis
+  deps: PlanSchedulerQueueDeps
+}): WorkerHandle {
+  const handle = planScheduler.startWorker({
+    deps: options.deps,
+    registerSignals: options.registerSignals,
+    connectionProvider: options.connectionProvider,
+  })
 
   // Recover active schedules on startup
-  planSchedulerService.recoverActiveSchedules().catch((err: unknown) => {
-    serverLogger.error`Plan scheduler startup recovery failed: ${err}`
-  })
+  void Effect.runFork(
+    options.deps.planSchedulerService.recoverActiveSchedules().pipe(
+      Effect.mapError((cause) => toPlanSchedulerQueueError('recover-active-schedules', cause)),
+      Effect.catchTag('PlanSchedulerQueueError', (error) =>
+        Effect.sync(() => {
+          serverLogger.error`Plan scheduler startup recovery failed: ${error.message}`
+        }),
+      ),
+    ),
+  )
 
   // Seed deadline checks from current runtime state. Subsequent checks are
   // re-seeded by the queue job after each sweep and by schedule fire events.
-  planDeadlineService.recoverDeadlineChecks().catch((err: unknown) => {
-    serverLogger.error`Plan deadline recovery failed: ${err}`
-  })
+  void Effect.runFork(
+    options.deps.planDeadlineService.recoverDeadlineChecks().pipe(
+      Effect.mapError((cause) => toPlanSchedulerQueueError('recover-deadline-checks', cause)),
+      Effect.catchTag('PlanSchedulerQueueError', (error) =>
+        Effect.sync(() => {
+          serverLogger.error`Plan deadline recovery failed: ${error.message}`
+        }),
+      ),
+    ),
+  )
 
   return handle
 }
 
-if (import.meta.main) {
-  startPlanSchedulerWorker()
-}
+runStandaloneQueueWorker((runtime) => {
+  const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))
+  startPlanSchedulerWorker({
+    connectionProvider: () => resolve(RedisServiceTag).getConnectionForBullMQ(),
+    deps: {
+      databaseService: resolve(DatabaseServiceTag),
+      planSchedulerService: resolve(PlanSchedulerServiceTag),
+      planDeadlineService: resolve(PlanDeadlineServiceTag),
+      planExecutorService: resolve(PlanExecutorServiceTag),
+      planCycleService: resolve(PlanCycleServiceTag),
+    },
+  })
+})

package/src/queues/post-chat-memory.queue.ts

@@ -1,9 +1,13 @@
-type OrganizationOnboardStatus = string
 import type { Job } from 'bullmq'
+import { Effect } from 'effect'
+import type { Context } from 'effect'
+import type IORedis from 'ioredis'
 
-import { databaseService } from '../db/service'
-import { memoryService } from '../services/memory.service'
-import { createQueueFactory } from './queue-factory'
+import type { MaybeAwaitableService } from '../effect/awaitable-effect'
+import { DatabaseServiceTag, RedisServiceTag } from '../effect/services'
+import { MemoryServiceTag } from '../services/memory/memory.service'
+import { createQueueFactoryWithDeps } from './queue-factory'
+import { runStandaloneQueueWorker } from './standalone-worker'
 
 interface PostChatMemoryMessage {
   role: 'user' | 'agent'
@@ -17,7 +21,7 @@ interface PostChatMemoryExtractionJob {
   sourceId: string
   source?: string
   sourceMetadata?: Record<string, unknown>
-  onboardStatus?: OrganizationOnboardStatus
+  onboardStatus?: string
   userMessage: string
   historyMessages: PostChatMemoryMessage[]
   agentMessages: Array<{ content: string; agentName?: string }>
@@ -25,9 +29,13 @@ interface PostChatMemoryExtractionJob {
   attachmentContext?: string
 }
 
-async function processPostChatMemoryJob(job: Job<PostChatMemoryExtractionJob>): Promise<void> {
-  await databaseService.connect()
+interface PostChatMemoryQueueDeps {
+  databaseService: Context.Service.Shape<typeof DatabaseServiceTag>
+  memoryService: MaybeAwaitableService<Context.Service.Shape<typeof MemoryServiceTag>>
+}
 
+function processPostChatMemoryJob(deps: PostChatMemoryQueueDeps, job: Job<PostChatMemoryExtractionJob>): Promise<void> {
+  const { memoryService } = deps
   const data = job.data
   const userMessage = data.userMessage.trim()
   const agentMessages = data.agentMessages
@@ -37,7 +45,9 @@ async function processPostChatMemoryJob(job: Job<PostChatMemoryExtractionJob>):
     }))
     .filter((item) => item.content.length > 0)
 
-  if (!userMessage || agentMessages.length === 0) return
+  if (!userMessage || agentMessages.length === 0) {
+    return Promise.resolve()
+  }
 
   const joinedOutput = agentMessages
     .map((item) => (item.agentName ? `[${item.agentName}] ${item.content}` : item.content))
@@ -51,23 +61,27 @@ async function processPostChatMemoryJob(job: Job<PostChatMemoryExtractionJob>):
     ),
   ]
 
-  await memoryService.addConversationMemories({
-    orgId: data.orgId,
-    input: userMessage,
-    output: joinedOutput,
-    sourceId: data.sourceId,
-    source: data.source,
-    sourceMetadata: data.sourceMetadata,
-    onboardStatus: data.onboardStatus,
-    ...(uniqueAgentNames.length > 0 ? { agentName: uniqueAgentNames[0] } : {}),
-    historyMessages: data.historyMessages,
-    memoryBlock: data.memoryBlock,
-    attachmentContext: data.attachmentContext,
-    agentNames: uniqueAgentNames,
-  })
+  return Effect.runPromise(
+    Effect.asVoid(
+      memoryService.addConversationMemories({
+        orgId: data.orgId,
+        input: userMessage,
+        output: joinedOutput,
+        sourceId: data.sourceId,
+        source: data.source,
+        sourceMetadata: data.sourceMetadata,
+        onboardStatus: data.onboardStatus,
+        ...(uniqueAgentNames.length > 0 ? { agentName: uniqueAgentNames[0] } : {}),
+        historyMessages: data.historyMessages,
+        memoryBlock: data.memoryBlock,
+        attachmentContext: data.attachmentContext,
+        agentNames: uniqueAgentNames,
+      }),
+    ),
+  )
 }
 
-const postChatMemory = createQueueFactory<PostChatMemoryExtractionJob>({
+const postChatMemory = createQueueFactoryWithDeps<PostChatMemoryExtractionJob, PostChatMemoryQueueDeps>({
   name: 'post-chat-memory',
   displayName: 'Post-chat memory',
   jobName: 'extract-memory',
@@ -76,14 +90,30 @@ const postChatMemory = createQueueFactory<PostChatMemoryExtractionJob>({
   maxStalledCount: 10,
   stalledInterval: 120_000,
   defaultJobOptions: { attempts: 3, backoff: { type: 'exponential', delay: 2_000 } },
+  prepare: ({ databaseService }) => databaseService.connect(),
   processor: processPostChatMemoryJob,
 })
 
 export function enqueuePostChatMemory(job: PostChatMemoryExtractionJob, options?: { dedupeKey?: string }) {
   return postChatMemory.enqueue(job, options?.dedupeKey ? { jobId: options.dedupeKey } : undefined)
 }
-export const startPostChatMemoryWorker = postChatMemory.startWorker
 
-if (import.meta.main) {
-  startPostChatMemoryWorker()
+export function startPostChatMemoryWorker(options: {
+  registerSignals?: boolean
+  connectionProvider: () => IORedis
+  deps: PostChatMemoryQueueDeps
+}) {
+  return postChatMemory.startWorker({
+    deps: options.deps,
+    registerSignals: options.registerSignals,
+    connectionProvider: options.connectionProvider,
+  })
 }
+
+runStandaloneQueueWorker((runtime) => {
+  const resolve = <I, T>(tag: Context.Key<I, T>): T => runtime.runSync(Effect.service(tag))
+  startPostChatMemoryWorker({
+    connectionProvider: () => resolve(RedisServiceTag).getConnectionForBullMQ(),
+    deps: { databaseService: resolve(DatabaseServiceTag), memoryService: resolve(MemoryServiceTag) },
+  })
+})

package/src/queues/queue-factory.ts

@@ -1,24 +1,50 @@
 import { Queue, Worker } from 'bullmq'
 import type { Job, JobsOptions, QueueOptions, WorkerOptions } from 'bullmq'
+import { Effect, Schema } from 'effect'
 import type IORedis from 'ioredis'
 
+import type { LotaLogger } from '../config/logger'
 import { serverLogger } from '../config/logger'
-import { getRedisConnectionForBullMQ } from '../redis'
-import { queueJobService } from '../services/queue-job.service'
+import { getCurrentRuntime } from '../effect/runtime-ref'
+import { RedisServiceTag } from '../effect/services'
+import type { TrackedBullJobLike } from '../services/queue-job.service'
 import {
   attachWorkerEvents,
   createTracedWorkerProcessor,
   createWorkerShutdown,
   DEFAULT_JOB_RETENTION,
   registerShutdownSignals,
+  getQueueJobService,
 } from '../workers/worker-utils'
 import type { WorkerHandle } from '../workers/worker-utils'
 
+class QueueFactoryError extends Schema.TaggedErrorClass<QueueFactoryError>()('@lota-sdk/core/QueueFactoryError', {
+  message: Schema.String,
+  cause: Schema.optional(Schema.Defect),
+}) {}
+
+function getDefaultQueueConnectionProvider(): () => IORedis {
+  const redis = getCurrentRuntime().runSync(Effect.service(RedisServiceTag))
+  return () => redis.getConnectionForBullMQ()
+}
+
+type QueueShape<TJob> = Queue<TJob, unknown, string, TJob, unknown, string>
+type QueueMethod = 'add' | 'close' | 'remove' | 'removeDeduplicationKey' | 'removeJobScheduler'
+
+const queueMethodsThatWaitForClose = new Set<QueueMethod>([
+  'add',
+  'close',
+  'remove',
+  'removeDeduplicationKey',
+  'removeJobScheduler',
+])
+
 interface QueueFactoryConfigBase {
   name: string
   displayName: string
   jobName: string
   concurrency: number
+  logger?: LotaLogger
   lockDuration?: number
   stalledInterval?: number
   maxStalledCount?: number
@@ -27,6 +53,7 @@ interface QueueFactoryConfigBase {
 }
 
 interface QueueFactoryConfigInline<TJob> extends QueueFactoryConfigBase {
+  prepare?: (job: Job<TJob>) => Promise<void>
   processor: (job: Job<TJob>) => Promise<unknown>
   processorPath?: never
 }
@@ -38,93 +65,208 @@ interface QueueFactoryConfigFile extends QueueFactoryConfigBase {
 
 export type QueueFactoryConfig<TJob> = QueueFactoryConfigInline<TJob> | QueueFactoryConfigFile
 
+interface QueueFactoryWithDepsConfig<TJob, TDeps> extends QueueFactoryConfigBase {
+  prepare?: (deps: TDeps, job: Job<TJob>) => Promise<void>
+  processor: (deps: TDeps, job: Job<TJob>) => Promise<unknown>
+}
+
+interface QueueWorkerConfigInline<TJob> {
+  prepare?: (job: Job<TJob>) => Promise<void>
+  processor: (job: Job<TJob>) => Promise<unknown>
+  processorPath?: never
+}
+
+interface QueueWorkerConfigFile {
+  processor?: never
+  processorPath: string
+}
+
+type QueueWorkerConfig<TJob> = QueueWorkerConfigInline<TJob> | QueueWorkerConfigFile
+
+export interface QueueFactoryWorkerOptions {
+  registerSignals?: boolean
+  connectionProvider?: () => IORedis
+}
+
 export interface QueueFactory<TJob> {
-  getQueue: () => Queue<TJob, unknown, string, TJob, unknown, string>
+  getQueue: () => QueueShape<TJob>
   enqueue: (job: TJob, options?: JobsOptions) => Promise<void>
-  startWorker: (options?: { registerSignals?: boolean }) => WorkerHandle
+  startWorker: (options?: QueueFactoryWorkerOptions) => WorkerHandle
 }
 
-export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): QueueFactory<TJob> {
-  type QueueShape = Queue<TJob, unknown, string, TJob, unknown, string>
+export interface QueueFactoryWithDeps<TJob, TDeps> {
+  getQueue: () => QueueShape<TJob>
+  enqueue: (job: TJob, options?: JobsOptions) => Promise<void>
+  startWorker: (options: QueueFactoryWorkerOptions & { deps: TDeps }) => WorkerHandle
+}
 
-  let _queue: QueueShape | null = null
-  let _queueConnection: IORedis | null = null
+export function recordEnqueuedJobMetadata(params: {
+  queueName: string
+  job: Omit<TrackedBullJobLike, 'queueName'>
+  logger?: LotaLogger
+}): Effect.Effect<string | undefined> {
+  const logger = params.logger ?? serverLogger
+  return getQueueJobService()
+    .recordEnqueued({ queueName: params.queueName, ...params.job })
+    .pipe(
+      Effect.tapError((error) =>
+        Effect.sync(() => {
+          logger.error`Failed to persist queued job metadata (queue=${params.queueName}, job=${params.job.id}): ${error}`
+        }),
+      ),
+      Effect.orElseSucceed(() => undefined),
+    )
+}
 
-  const getConnection = (): IORedis => config.connectionProvider?.() ?? getRedisConnectionForBullMQ()
+function createQueueFactoryRuntime<TJob>(config: QueueFactoryConfigBase): {
+  getQueue: () => QueueShape<TJob>
+  enqueue: (job: TJob, options?: JobsOptions) => Promise<void>
+  startWorker: (workerConfig: QueueWorkerConfig<TJob>, options?: QueueFactoryWorkerOptions) => WorkerHandle
+} {
+  type State = {
+    queue: QueueShape<TJob> | null
+    rawQueue: QueueShape<TJob> | null
+    connection: IORedis | null
+    pendingClose: Promise<void> | null
+  }
 
-  const getQueue = (): QueueShape => {
-    const connection = getConnection()
-    const shouldRecreateQueue =
-      _queue === null ||
-      _queueConnection === null ||
-      _queueConnection !== connection ||
-      _queueConnection.status === 'close' ||
-      _queueConnection.status === 'end'
-
-    if (shouldRecreateQueue) {
-      if (_queue) {
-        void _queue.close().catch((error: unknown) => {
-          serverLogger.warn`Failed to close stale ${config.displayName} queue: ${error}`
-        })
-      }
+  let state: State = { queue: null, rawQueue: null, connection: null, pendingClose: null }
 
-      _queue = new Queue<TJob, unknown, string, TJob, unknown, string>(config.name, {
-        connection: connection as QueueOptions['connection'],
-        defaultJobOptions: { ...DEFAULT_JOB_RETENTION, ...config.defaultJobOptions },
-      })
-      _queueConnection = connection
-    }
-    if (_queue === null) {
-      throw new Error(`Failed to initialize queue: ${config.name}`)
+  const resolveConnectionProvider = (): (() => IORedis) =>
+    config.connectionProvider ?? getDefaultQueueConnectionProvider()
+
+  const getConnection = (): IORedis => resolveConnectionProvider()()
+
+  const waitForPendingClose = (): Promise<void> => {
+    const pendingClose = state.pendingClose
+    if (!pendingClose) {
+      return Promise.resolve()
     }
-    return _queue
+
+    return pendingClose.finally(() => {
+      if (state.pendingClose === pendingClose) {
+        state.pendingClose = null
+      }
+    })
   }
 
-  const jobName = config.jobName
-  const toData = (job: TJob) => job
-
-  const enqueue = async (job: TJob, options?: JobsOptions): Promise<void> => {
-    const queuedJob = await getQueue().add(jobName, toData(job), options)
-    try {
-      await queueJobService.recordEnqueued({
-        queueName: config.name,
-        id: queuedJob.id,
-        name: queuedJob.name,
-        data: queuedJob.data,
-        opts: queuedJob.opts,
-        attemptsMade: queuedJob.attemptsMade,
-        timestamp: queuedJob.timestamp,
-      })
-    } catch (error) {
-      serverLogger.error`Failed to persist queued job metadata (queue=${config.name}, job=${queuedJob.id}): ${error}`
+  const wrapQueue = (queue: QueueShape<TJob>): QueueShape<TJob> =>
+    new Proxy(queue, {
+      get(target, property, receiver) {
+        if (typeof property !== 'string') {
+          return Reflect.get(target, property, receiver) as unknown
+        }
+
+        const value = (target as unknown as Record<string, unknown>)[property]
+        if (typeof value !== 'function' || !queueMethodsThatWaitForClose.has(property as QueueMethod)) {
+          return value
+        }
+
+        return (...args: Array<unknown>) =>
+          waitForPendingClose().then(() =>
+            Reflect.apply(value as (...methodArgs: Array<unknown>) => unknown, target, args),
+          )
+      },
+    })
+
+  const getQueue = (): QueueShape<TJob> => {
+    const connection = getConnection()
+    const isStale =
+      state.rawQueue === null ||
+      state.queue === null ||
+      state.connection === null ||
+      state.connection !== connection ||
+      state.connection.status === 'close' ||
+      state.connection.status === 'end'
+
+    if (!isStale && state.queue) {
+      return state.queue
+    }
+
+    if (state.rawQueue) {
+      const staleQueue = state.rawQueue
+      const previousPendingClose = state.pendingClose ?? Promise.resolve()
+      state.pendingClose = previousPendingClose
+        .catch(() => undefined)
+        .then(() =>
+          staleQueue.close().catch((error: unknown) => {
+            serverLogger.warn`Failed to close stale ${config.displayName} queue: ${error}`
+          }),
+        )
+        .then(() => undefined)
     }
+
+    const queue = new Queue<TJob, unknown, string, TJob, unknown, string>(config.name, {
+      connection: connection as QueueOptions['connection'],
+      defaultJobOptions: { ...DEFAULT_JOB_RETENTION, ...config.defaultJobOptions },
+    })
+    const wrappedQueue = wrapQueue(queue)
+
+    state = { queue: wrappedQueue, rawQueue: queue, connection, pendingClose: state.pendingClose }
+    return wrappedQueue
   }
 
-  const startWorker = (options: { registerSignals?: boolean } = {}): WorkerHandle => {
-    const { registerSignals = import.meta.main } = options
+  const enqueue = (job: TJob, options?: JobsOptions): Promise<void> =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const queuedJob = yield* Effect.tryPromise({
+          try: () => getQueue().add(config.jobName, job, options),
+          catch: (cause) =>
+            new QueueFactoryError({ message: `Failed to enqueue job on queue "${config.name}".`, cause }),
+        })
+        yield* recordEnqueuedJobMetadata({ queueName: config.name, job: queuedJob, logger: config.logger })
+      }),
+    )
+
+  const startWorker = (
+    workerConfig: QueueWorkerConfig<TJob>,
+    options: QueueFactoryWorkerOptions = {},
+  ): WorkerHandle => {
+    const { registerSignals = import.meta.main, connectionProvider } = options
+    const logger = config.logger ?? serverLogger
 
     const workerOptions: WorkerOptions = {
-      connection: getConnection() as QueueOptions['connection'],
+      connection: (connectionProvider ?? resolveConnectionProvider())() as QueueOptions['connection'],
       concurrency: config.concurrency,
       ...(config.lockDuration !== undefined ? { lockDuration: config.lockDuration } : {}),
       ...(config.stalledInterval !== undefined ? { stalledInterval: config.stalledInterval } : {}),
       ...(config.maxStalledCount !== undefined ? { maxStalledCount: config.maxStalledCount } : {}),
     }
 
-    const worker = config.processorPath
-      ? new Worker(config.name, config.processorPath, workerOptions)
+    const worker = workerConfig.processorPath
+      ? new Worker(config.name, workerConfig.processorPath, workerOptions)
       : new Worker(
           config.name,
-          createTracedWorkerProcessor(config.name, (config as QueueFactoryConfigInline<TJob>).processor),
+          createTracedWorkerProcessor(config.name, (job) =>
+            Effect.runPromise(
+              Effect.gen(function* () {
+                const inlineWorkerConfig = workerConfig as QueueWorkerConfigInline<TJob>
+                const typedJob = job as Job<TJob>
+                const prepare = inlineWorkerConfig.prepare
+                if (prepare) {
+                  yield* Effect.tryPromise({
+                    try: () => prepare(typedJob),
+                    catch: (cause) =>
+                      new QueueFactoryError({ message: `Worker prepare failed for queue "${config.name}".`, cause }),
+                  })
+                }
+                return yield* Effect.tryPromise({
+                  try: () => inlineWorkerConfig.processor(typedJob),
+                  catch: (cause) =>
+                    new QueueFactoryError({ message: `Worker processor failed for queue "${config.name}".`, cause }),
+                })
+              }),
+            ),
+          ),
           workerOptions,
         )
 
-    attachWorkerEvents(worker, config.displayName, serverLogger)
+    attachWorkerEvents(worker, config.displayName, logger)
 
-    const shutdown = createWorkerShutdown(worker, config.displayName, serverLogger)
+    const shutdown = createWorkerShutdown(worker, config.displayName, logger)
 
     if (registerSignals) {
-      registerShutdownSignals({ name: config.displayName, shutdown, logger: serverLogger })
+      registerShutdownSignals({ name: config.displayName, shutdown, logger })
     }
 
     return { worker, shutdown }
@@ -132,3 +274,29 @@ export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): Queu
 
   return { getQueue, enqueue, startWorker }
 }
+
+export function createQueueFactory<TJob>(config: QueueFactoryConfig<TJob>): QueueFactory<TJob> {
+  const runtime = createQueueFactoryRuntime<TJob>(config)
+  return {
+    getQueue: runtime.getQueue,
+    enqueue: runtime.enqueue,
+    startWorker: (options) => runtime.startWorker(config, options),
+  }
+}
+
+export function createQueueFactoryWithDeps<TJob, TDeps>(
+  config: QueueFactoryWithDepsConfig<TJob, TDeps>,
+): QueueFactoryWithDeps<TJob, TDeps> {
+  const runtime = createQueueFactoryRuntime<TJob>(config)
+  const prepare = config.prepare
+
+  return {
+    getQueue: runtime.getQueue,
+    enqueue: runtime.enqueue,
+    startWorker: ({ deps, ...options }) =>
+      runtime.startWorker(
+        { prepare: prepare ? (job) => prepare(deps, job) : undefined, processor: (job) => config.processor(deps, job) },
+        options,
+      ),
+  }
+}