Forem: Leonardo Marciano

Encore.ts + Effect.ts : Building a Production-Ready Task Management System with Functional TypeScript

Leonardo Marciano — Thu, 12 Mar 2026 03:04:16 +0000

Introduction

What if your backend could have typed errors that compile down to HTTP status codes, automatic request batching, fiber-based concurrency with semaphores and queues, and auto-provisioned databases, PubSub, and object storage... all in TypeScript?

That's what happens when you combine Effect.ts and Encore.ts.

Effect.ts gives you a functional programming toolkit for TypeScript: composable effects, typed errors, dependency injection via layers, streams, concurrency primitives (fibers, semaphores, queues), and a schema system that makes Zod look like a toy.

Encore.ts gives you infrastructure-as-code: declare a SQLDatabase, Topic, Bucket, or CronJob in your TypeScript code, and Encore provisions it automatically. Locally, in preview environments, and in production. No Terraform(Must read: The Last Year of Terraform), no Docker Compose, no YAML.

Together, they're remarkably complementary. Effect handles the how (composition, error handling, concurrency), Encore handles the what (databases, messaging, auth, deployment).

In this article, I'll walk you through a Task Management System (think mini Jira/Linear) we built with 7 microservices, covering virtually every major feature of both frameworks. This isn't a toy example. It's a reference architecture you can study, fork, and build on.

System Architecture

Here's the bird's-eye view of our system:

Client Request
    │
    ▼
┌─────────┐     ┌──────┐
│ Gateway │────▶│ auth │ validates JWT token
└────┬────┘     └──────┘
     │
     ▼
┌────────────┐
│ Middleware │ enriches request (timing/tracing)
└─────┬──────┘
      │
      ├──▶ [user]          ◀── service-to-service ── [project], [auth]
      │      ├── users DB
      │      └── Effect Cache (permissions)
      │
      ├──▶ [project]
      │      └── projects DB + project_members
      │
      ├──▶ [task]          ──▶ publishes to PubSub topics
      │      ├── tasks DB + comments
      │      ├── CronJob (stale task check)
      │      └── WebSocket streams (activity feed)
      │
      ├──▶ [notification]  ◀── subscribes to PubSub topics
      │      ├── notifications DB
      │      ├── Queue + Deferred (async dispatch)
      │      └── WebSocket stream (real-time push)
      │
      ├──▶ [analytics]     ◀── subscribes to PubSub topics
      │      ├── analytics DB (events + daily_stats)
      │      ├── Encore Metrics (Counter, Gauge)
      │      └── Effect Stream/Sink (aggregation pipelines)
      │
      └──▶ [storage]
             ├── Encore Bucket (object storage)
             └── Effect Semaphore (rate limiting)

Each service has its own encore.service.ts, its own database (auto-provisioned by Encore), and communicates via PubSub topics for async events or direct service-to-service calls for synchronous operations.

The Bridge: Connecting Effect.ts to Encore.ts

This is the single most important pattern in the entire codebase. Encore expects your API handlers to be async functions that return Promises. Effect programs return Effect<A, E> values. We need a bridge.

Here's runEffect. Every Encore endpoint calls this:

import { Cause, Chunk, Effect, Exit, Match, pipe } from "effect"
import { APIError } from "encore.dev/api"
import type { AppError } from "./errors.js"

export const runEffect = async <A, E extends AppError>(
  effect: Effect.Effect<A, E>,
): Promise<A> => {
  const exit = await Effect.runPromiseExit(
    effect.pipe(
      Effect.withSpan("encore-handler"),
      Effect.annotateLogs("runtime", "encore"),
    ),
  )

  if (Exit.isSuccess(exit)) {
    return exit.value
  }

  const cause = exit.cause

  // Expected errors → translate to APIError
  if (Cause.isFailType(cause)) {
    throw effectErrorToAPIError(cause.error as AppError)
  }

  // Fiber interruption → aborted
  if (Cause.isInterruptType(cause)) {
    throw APIError.aborted("Request was interrupted")
  }

  // Defects (bugs) → internal error
  if (Cause.isDieType(cause)) {
    console.error("Unexpected defect:", cause.defect)
    throw APIError.internal("Internal server error")
  }

  // Composite causes → extract first failure
  const failures = Chunk.toArray(Cause.failures(cause))
  if (failures.length > 0) {
    throw effectErrorToAPIError(failures[0] as AppError)
  }

  throw APIError.internal("Unknown error")
}

The key insight: Effect's Exit type distinguishes between expected failures (your domain errors), defects (bugs/panics), and interruptions (cancelled fibers). We handle each differently.

The error translation uses Effect's Match module for exhaustive mapping:

export const effectErrorToAPIError = (error: AppError): APIError =>
  pipe(
    error,
    Match.value,
    Match.tag("NotFoundError", (e) =>
      APIError.notFound(`${e.entity} '${e.id}' not found`)),
    Match.tag("ValidationError", (e) =>
      APIError.invalidArgument(`${e.field}: ${e.message}`)),
    Match.tag("AuthenticationError", (e) =>
      APIError.unauthenticated(e.reason)),
    Match.tag("AuthorizationError", (e) =>
      APIError.permissionDenied(
        `User '${e.userId}' cannot '${e.action}' on '${e.resource}'`)),
    Match.tag("RateLimitError", (e) =>
      APIError.resourceExhausted(`Rate limited. Retry after ${e.retryAfter}s`)),
    Match.tag("DatabaseError", (e) =>
      APIError.internal(`Database error in '${e.operation}'`)),
    Match.tag("InvalidStateTransitionError", (e) =>
      APIError.failedPrecondition(
        `Cannot transition ${e.entity} from '${e.from}' to '${e.to}'`)),
    // ... all 10 error types mapped
    Match.exhaustive, // Compiler error if you miss one!
  )

Match.exhaustive is the magic. If you add a new error type to AppError but forget to handle it here, TypeScript won't compile. No more silent 500s from unhandled error cases.

And this is how every Encore endpoint looks:

import { api } from "encore.dev/api"
import { Effect } from "effect"
import { TaskService, TaskServiceLive } from "./task-service.js"
import { runEffect } from "../shared/effect-encore-bridge.js"

export const getTask = api(
  { expose: true, method: "GET", path: "/tasks/:id", auth: true },
  async ({ id }: { id: string }): Promise<TaskResponse> =>
    runEffect(
      Effect.gen(function* () {
        const service = yield* TaskService
        return yield* service.getById(TaskId(id))
      }).pipe(Effect.provide(TaskServiceLive))
    )
)

Clean, consistent, and every error is automatically translated to the correct HTTP status code.

Type Safety with Branded Types

A UserId is a string. A ProjectId is also a string. But they are not the same thing. Effect's Brand module prevents you from accidentally passing one where the other is expected:

import { Brand, Order, Equivalence, Equal, Hash } from "effect"

export type UserId = string & Brand.Brand<"UserId">
export const UserId = Brand.nominal<UserId>()

export type ProjectId = string & Brand.Brand<"ProjectId">
export const ProjectId = Brand.nominal<ProjectId>()

export type TaskId = string & Brand.Brand<"TaskId">
export const TaskId = Brand.nominal<TaskId>()

Now service.getById(TaskId("abc")) compiles, but service.getById(UserId("abc")) is a type error. This catches entire classes of bugs at compile time. Imagine an accidental WHERE user_id = $projectId query that silently returns nothing.

We also get custom ordering for sorting:

export type TaskPriority = "critical" | "high" | "medium" | "low"

const priorityRank: Record<TaskPriority, number> = {
  critical: 0, high: 1, medium: 2, low: 3,
}

export const TaskPriorityOrder: Order.Order<TaskPriority> =
  Order.mapInput(Order.number, (p: TaskPriority) => priorityRank[p])

And custom Equal + Hash implementations for use in HashMap/HashSet:

export class ProjectMemberKey implements Equal.Equal {
  constructor(readonly projectId: ProjectId, readonly userId: UserId) {}

  [Equal.symbol](that: Equal.Equal): boolean {
    if (that instanceof ProjectMemberKey) {
      return this.projectId === that.projectId && this.userId === that.userId
    }
    return false
  }

  [Hash.symbol](): number {
    return Hash.combine(Hash.hash(this.projectId))(Hash.hash(this.userId))
  }
}

Typed Error Hierarchy

Every error in the system extends Data.TaggedError, making them yieldable inside Effect.gen generators:

import { Data } from "effect"

export class NotFoundError extends Data.TaggedError("NotFoundError")<{
  readonly entity: string
  readonly id: string
}> {}

export class ValidationError extends Data.TaggedError("ValidationError")<{
  readonly field: string
  readonly message: string
}> {}

export class InvalidStateTransitionError extends Data.TaggedError(
  "InvalidStateTransitionError"
)<{
  readonly entity: string
  readonly from: string
  readonly to: string
}> {}

// ... 10 total error types

export type AppError =
  | DatabaseError | NotFoundError | ValidationError
  | AuthenticationError | AuthorizationError | ConflictError
  | RateLimitError | ExternalServiceError | TimeoutError
  | InvalidStateTransitionError

The discriminated union AppError is what makes Match.exhaustive work in the bridge. Each error carries structured context (not just a message string), so the API response can be precise:

TaggedError	HTTP Status	Example Message
`NotFoundError`	404	`Task 'abc-123' not found`
`ValidationError`	400	`title: Must be at least 1 character`
`AuthenticationError`	401	`Invalid or expired token`
`AuthorizationError`	403	`User 'u1' cannot 'delete' on 'Project'`
`ConflictError`	409	`User: Email already exists`
`RateLimitError`	429	`Rate limited. Retry after 30s`
`InvalidStateTransitionError`	400	`Cannot transition Task from 'done' to 'in_progress'`
`DatabaseError`	500	`Database error in 'queryRow'`
`ExternalServiceError`	503	`Service 'object-storage' unavailable`
`TimeoutError`	504	`'queryRow' timed out after 5000ms`

Schema: Bidirectional Validation

Effect Schema handles two things that Encore's built-in validation doesn't: domain object validation and database row transformation.

Encore validates at the HTTP boundary (email format, string length). Effect Schema validates at the domain boundary and transforms between database rows (snake_case) and domain objects (camelCase):

import { Schema } from "effect"

export class TaskSchema extends Schema.Class<TaskSchema>("TaskSchema")({
  id: Schema.String.pipe(Schema.brand("TaskId")),
  title: Schema.String.pipe(
    Schema.minLength(1), Schema.maxLength(200),
    Schema.annotations({ description: "Task title" })
  ),
  status: Schema.optionalWith(TaskStatusSchema, {
    default: () => "backlog" as const
  }),
  priority: Schema.optionalWith(TaskPrioritySchema, {
    default: () => "medium" as const
  }),
  storyPoints: Schema.OptionFromNullOr(
    Schema.Number.pipe(Schema.int(), Schema.between(1, 21))
  ),
  // ...
}) {}

The bidirectional transform between DB rows and domain objects:

export const TaskFromRow = Schema.transform(
  // From: database row (snake_case)
  Schema.Struct({
    id: Schema.String,
    title: Schema.String,
    assignee_id: Schema.NullOr(Schema.String),
    project_id: Schema.String,
    created_at: Schema.String,
    // ...
  }),
  // To: domain object (camelCase + branded)
  Schema.Struct({
    id: Schema.String.pipe(Schema.brand("TaskId")),
    title: Schema.String,
    assigneeId: Schema.NullOr(Schema.String.pipe(Schema.brand("UserId"))),
    projectId: Schema.String.pipe(Schema.brand("ProjectId")),
    createdAt: Schema.String,
    // ...
  }),
  {
    strict: true,
    decode: (row) => ({
      id: row.id as any,
      title: row.title,
      assigneeId: row.assignee_id as any,
      projectId: row.project_id as any,
      createdAt: row.created_at,
    }),
    encode: (task) => ({
      id: task.id,
      title: task.title,
      assignee_id: task.assigneeId,
      project_id: task.projectId,
      created_at: task.createdAt,
    }),
  }
)

Passwords use Schema.Redacted so they never appear in logs:

export const PasswordHashSchema = Schema.Redacted(Schema.String)

Resilience: Retry, Timeout, Schedule

Every database query in the system goes through a retry + timeout wrapper:

import { Effect, Schedule, Duration, pipe, Option, Chunk } from "effect"

// Exponential backoff (100ms, 200ms, 400ms) + jitter + max 3 retries
export const dbRetrySchedule = Schedule.exponential("100 millis").pipe(
  Schedule.intersect(Schedule.recurs(3)),
  Schedule.jittered
)

export const queryRowEffect = <T>(
  db: SQLDatabase,
  queryFn: () => Promise<T | null>
): Effect.Effect<Option.Option<T>, DatabaseError> =>
  pipe(
    Effect.tryPromise({
      try: () => queryFn(),
      catch: (e) => new DatabaseError({ operation: "queryRow", cause: e }),
    }),
    Effect.map(Option.fromNullable),
    Effect.retry(dbRetrySchedule),
    Effect.timeout(Duration.seconds(5)),
    Effect.catchTag("TimeoutException", () =>
      Effect.fail(new DatabaseError({
        operation: "queryRow",
        cause: "Query timed out after 5s"
      }))
    )
  )

Schedule.intersect combines two schedules: "exponential backoff" AND "max 3 attempts". Schedule.jittered adds randomness to prevent thundering herd problems when multiple requests retry simultaneously.

The task scheduler demonstrates more advanced Schedule combinators:

import { CronJob } from "encore.dev/cron"
import { Schedule } from "effect"

// Encore CronJob triggers the endpoint every hour
const _ = new CronJob("stale-task-check", {
  title: "Check for stale tasks",
  every: "1h",
  endpoint: checkStaleTasks,
})

// Effect Schedule for retry within the job
const staleCheckSchedule = Schedule.exponential("1 second").pipe(
  Schedule.jittered,
  Schedule.intersect(Schedule.recurs(3)),
  Schedule.union(Schedule.spaced(Duration.seconds(30))),
)

State Machine with Match

Task status transitions follow strict rules. You can't go from backlog directly to done. The state machine is implemented with Effect's Match module:

import { Data, Match } from "effect"

class StateTransition extends Data.Class<{
  readonly from: string
  readonly to: string
}> {}

const isValidTransition = (from: string, to: string): boolean =>
  Match.value(new StateTransition({ from, to })).pipe(
    Match.when({ from: "backlog", to: "todo" }, () => true),
    Match.when({ from: "todo", to: "in_progress" }, () => true),
    Match.when({ from: "todo", to: "cancelled" }, () => true),
    Match.when({ from: "in_progress", to: "in_review" }, () => true),
    Match.when({ from: "in_progress", to: "todo" }, () => true),
    Match.when({ from: "in_review", to: "done" }, () => true),
    Match.when({ from: "in_review", to: "in_progress" }, () => true),
    Match.when({ from: "done", to: "todo" }, () => true), // reopen
    Match.orElse(() => false),
  )

Used in the transition method:

transition: (id, newStatus) =>
  Effect.gen(function* () {
    const task = yield* repo.findById(id)
    const fromStatus = task.status

    if (!isValidTransition(fromStatus, newStatus)) {
      return yield* Effect.fail(
        new InvalidStateTransitionError({
          entity: "Task", from: fromStatus, to: newStatus,
        })
      )
    }

    const updated = yield* repo.update(id, { status: newStatus })
    return { task: updated, fromStatus }
  }).pipe(Effect.withSpan("TaskService.transition")),

Bulk updates use error accumulation. Each update is independent, and failures don't block successes:

bulkUpdateStatus: (updates) =>
  Effect.forEach(
    updates,
    (u) =>
      pipe(
        Effect.gen(function* () {
          const task = yield* repo.findById(u.id)
          if (!isValidTransition(task.status, u.status)) {
            return yield* Effect.fail(
              new InvalidStateTransitionError({
                entity: "Task", from: task.status, to: u.status,
              })
            )
          }
          return yield* repo.update(u.id, { status: u.status })
        }),
        Effect.either, // Convert to Either: Right(task) | Left(error)
      ),
    { concurrency: 5 }, // Process 5 at a time
  ),

The API returns { succeeded: Task[], failed: { id, error }[] } so the caller sees exactly what worked and what didn't.

Concurrency and Rate Limiting

Semaphore: Controlling Upload Concurrency

The storage service limits concurrent uploads to 10 using an Effect Semaphore:

import { Effect, Duration, pipe } from "effect"

export const makeUploadLimiter = Effect.gen(function* () {
  const semaphore = yield* Effect.makeSemaphore(10)

  return {
    withLimit: <A, E>(
      effect: Effect.Effect<A, E>
    ): Effect.Effect<A, E | RateLimitError> =>
      pipe(
        semaphore.withPermits(1)(effect),
        Effect.timeout(Duration.seconds(30)),
        Effect.catchTag("TimeoutException", () =>
          Effect.fail(new RateLimitError({ retryAfter: 30 }))
        )
      ),
  }
})

If all 10 permits are taken, the 11th upload waits. If it waits more than 30 seconds, it gets a 429 Too Many Requests response.

Queue + Deferred: Async Notification Dispatch

The notification service uses a bounded queue with completion signaling:

import { Deferred, Effect, Fiber, Queue } from "effect"

export const makeNotificationDispatcher = Effect.gen(function* () {
  const queue = yield* Queue.bounded<PendingNotification>(1000)
  const startGate = yield* Deferred.make<void>()

  // Background consumer fiber
  const consumer = yield* Effect.fork(
    Effect.gen(function* () {
      yield* Deferred.await(startGate) // Wait until ready

      yield* Effect.forever(
        Effect.gen(function* () {
          const notification = yield* Queue.take(queue)
          const result = yield* pipe(
            Effect.logInfo(`Dispatching to ${notification.userId}`),
            Effect.either,
          )
          // Signal completion back to the producer
          if (result._tag === "Right") {
            yield* Deferred.succeed(notification.completion, undefined)
          } else {
            yield* Deferred.fail(notification.completion, /* error */)
          }
        }),
      )
    }),
  )

  return {
    enqueue: (input) =>
      Effect.gen(function* () {
        const deferred = yield* Deferred.make<void, ExternalServiceError>()
        yield* Queue.offer(queue, { ...input, completion: deferred })
        return yield* Deferred.await(deferred) // Wait for processing
      }),
    start: Deferred.succeed(startGate, undefined),
    shutdown: pipe(Queue.shutdown(queue), Effect.flatMap(() => Fiber.interrupt(consumer))),
  }
})

Three primitives working together:

Queue.bounded(1000): Backpressure. If 1000 notifications are pending, producers wait.
Deferred: One-shot promise. Each notification gets a completion signal.
Fiber: Background consumer runs independently, interrupted on shutdown.

Automatic Batching with RequestResolver

When you need to load 50 tasks in a list view, you don't want 50 separate SQL queries. Effect's RequestResolver automatically batches them:

import { Effect, Request, RequestResolver } from "effect"

interface GetTaskById extends Request.Request<Task, NotFoundError> {
  readonly _tag: "GetTaskById"
  readonly id: TaskId
}

const GetTaskById = Request.tagged<GetTaskById>("GetTaskById")

const TaskBatchResolver = RequestResolver.makeBatched(
  (requests: ReadonlyArray<GetTaskById>) =>
    Effect.gen(function* () {
      const repo = yield* TaskRepo
      const ids = requests.map((r) => r.id)
      // ONE query instead of N
      const tasks = yield* repo.findByIds(ids)
      const taskMap = new Map(tasks.map((t) => [t.id, t]))

      for (const req of requests) {
        const task = taskMap.get(req.id)
        if (task) yield* Request.succeed(req, task)
        else yield* Request.fail(req,
          new NotFoundError({ entity: "Task", id: req.id }))
      }
    }),
)

// Usage: these calls are automatically batched!
export const getTasksBatched = (ids: TaskId[]) =>
  Effect.forEach(ids, (id) =>
    Effect.request(GetTaskById({ id }), TaskBatchResolver),
    { concurrency: "unbounded", batching: true }
  )

Call getTasksBatched(["a", "b", "c", ..., "z"]) and Effect will execute one SELECT ... WHERE id IN (...) query instead of 26 individual queries. The batching is transparent to the caller.

Reactive State: Ref, SynchronizedRef, SubscriptionRef

The task board maintains real-time state using three flavors of mutable references:

import {
  Data, Effect, HashMap, HashSet,
  Ref, SubscriptionRef, SynchronizedRef
} from "effect"

export class BoardState extends Data.Class<{
  readonly tasksByStatus: HashMap.HashMap<string, HashSet.HashSet<string>>
  readonly activeViewers: HashSet.HashSet<string>
  readonly lastUpdated: number
}> {}

export const makeBoardState = Effect.gen(function* () {
  // SynchronizedRef: atomic effectful updates
  const boardRef = yield* SynchronizedRef.make(
    new BoardState({
      tasksByStatus: HashMap.empty(),
      activeViewers: HashSet.empty(),
      lastUpdated: Date.now(),
    }),
  )

  // SubscriptionRef: observable — clients subscribe to changes
  const activityRef = yield* SubscriptionRef.make<ActivityEvent>(/* initial */)

  // Ref: simple counter
  const opsCounterRef = yield* Ref.make(0)

  return {
    moveTask: (taskId, fromStatus, toStatus) =>
      pipe(
        SynchronizedRef.updateEffect(boardRef, (state) =>
          Effect.gen(function* () {
            const fromSet = HashMap.get(state.tasksByStatus, fromStatus)
              .pipe(opt => opt._tag === "Some" ? opt.value : HashSet.empty())
            const toSet = HashMap.get(state.tasksByStatus, toStatus)
              .pipe(opt => opt._tag === "Some" ? opt.value : HashSet.empty())
            return new BoardState({
              tasksByStatus: pipe(
                state.tasksByStatus,
                HashMap.set(fromStatus, HashSet.remove(fromSet, taskId)),
                HashMap.set(toStatus, HashSet.add(toSet, taskId)),
              ),
              activeViewers: state.activeViewers,
              lastUpdated: Date.now(),
            })
          }),
        ),
        Effect.tap(() => Ref.update(opsCounterRef, (n) => n + 1)),
      ),

    // Stream of changes for WebSocket push
    activityStream: activityRef.changes,
  }
})

Ref: Simple mutable value (like useState but for Effect).
SynchronizedRef: Effectful atomic updates. The update function can do async work.
SubscriptionRef: Like SynchronizedRef, but consumers can subscribe to .changes, which exposes a Stream of every update.

Streams and Sinks for Data Processing

The analytics service processes events through Stream pipelines and collects results with Sinks:

import { Chunk, Stream, Schedule, Duration, Effect, pipe } from "effect"

export const aggregateEventsStream = (
  events: Stream.Stream<AnalyticsEvent>,
) =>
  pipe(
    events,
    Stream.grouped(100),          // Batch into chunks of 100
    Stream.map((chunk) => {       // Aggregate each batch
      const byProject = new Map<string, { created: number; completed: number }>()
      for (const event of chunk) {
        const projectId = event.metadata.projectId ?? "unknown"
        const current = byProject.get(projectId) ?? { created: 0, completed: 0 }
        if (event.eventType === "task_created") current.created++
        byProject.set(projectId, current)
      }
      return Array.from(byProject.entries()).map(([projectId, stats]) => ({
        projectId, ...stats,
      }))
    }),
    Stream.mapConcat((arr) => arr), // Flatten arrays
  )

// Running totals with stateful transformation
export const runningTotalsStream = (events: Stream.Stream<AnalyticsEvent>) =>
  Stream.mapAccum(events, 0, (total, event) => {
    const newTotal = total + 1
    return [newTotal, { total: newTotal, eventType: event.eventType }]
  })

Sinks consume streams and produce final results:

import { Sink, Effect, pipe } from "effect"

// Count all events
export const countEventsSink = Sink.foldLeft(
  0, (count, _event: AnalyticsEvent) => count + 1
)

// Aggregate by type
export const aggregateByTypeSink = Sink.foldLeft(
  new Map<string, number>(),
  (acc, event: AnalyticsEvent) => {
    acc.set(event.eventType, (acc.get(event.eventType) ?? 0) + 1)
    return acc
  }
)

// Compose: count then log
export const countAndLogSink = pipe(
  countEventsSink,
  Sink.zipRight(Sink.fromEffect(Effect.logInfo("Finished counting events"))),
)

Metrics at Two Levels

We track metrics at two levels. Encore metrics get exported to your cloud provider's monitoring. Effect metrics handle internal runtime observability:

import { Effect, Metric, MetricBoundaries, pipe } from "effect"
import { Counter, Gauge } from "encore.dev/metrics"

// Encore: infrastructure-level metrics
export const tasksCreatedTotal = new Counter("tasks_created_total")
export const activeUsersGauge = new Gauge("active_users")

// Effect: runtime-level metrics
export const taskProcessingDuration = Metric.histogram(
  "effect_task_processing_duration_ms",
  MetricBoundaries.linear({ start: 0, width: 100, count: 10 }),
)

// Helper: measure any effect's duration
export const trackDuration = <A, E>(
  effect: Effect.Effect<A, E>
): Effect.Effect<A, E> =>
  pipe(
    Effect.timed(effect),
    Effect.tap(([duration]) =>
      Metric.update(taskProcessingDuration,
        Number(duration) / 1_000_000)),
    Effect.map(([, result]) => result),
  )

Encore metrics appear in your cloud dashboard automatically. Effect metrics power internal observability: histogram boundaries, percentile tracking, fiber-level instrumentation.

Authentication: Gateway + Effect

Encore's authHandler + Gateway integrate well with Effect's Option and Either:

import { Effect, Either, Option, pipe } from "effect"
import { Gateway, type Header } from "encore.dev/api"
import { authHandler } from "encore.dev/auth"

const validateToken = (rawHeader: string) =>
  Effect.gen(function* () {
    // Extract Bearer token using Option
    const token = pipe(
      rawHeader,
      Option.liftPredicate((h) => h.startsWith("Bearer ")),
      Option.map((h) => h.slice(7)),
      Option.getOrElse(() => rawHeader),
    )

    if (!token) {
      return yield* new AuthenticationError({ reason: "Missing token" })
    }

    const tokenService = yield* TokenService
    const payload = yield* tokenService.verify(token)
    return { userID: payload.userId, role: payload.role, email: payload.email }
  })

export const auth = authHandler<AuthParams, AuthData>(async (params) => {
  const program = pipe(
    validateToken(params.authorization),
    Effect.provide(TokenServiceLive),
  )

  const result = await Effect.runPromise(Effect.either(program))

  return Either.match(result, {
    onLeft: (error) => { throw new Error(error.reason) },
    onRight: (data) => data,
  })
})

export const gateway = new Gateway({ authHandler: auth })

TokenService is a Context.Tag + Layer that wraps Encore's secret() for JWT signing:

import { secret } from "encore.dev/config"
const jwtSecret = secret("JWTSecret")

export const TokenServiceLive = Layer.succeed(TokenService, {
  sign: (payload) => Effect.try(() => { /* HMAC-SHA256 signing */ }),
  verify: (token) => Effect.try(() => { /* Validate + decode */ }),
})

PubSub: Cross-Service Events

Encore Topics define cross-service event channels. Subscribers in other services react to them:

// In task/task-api.ts — Topics MUST be defined in services
import { Topic } from "encore.dev/pubsub"

export const taskCreatedTopic = new Topic<TaskCreatedEvent>("task-created", {
  deliveryGuarantee: "at-least-once",
})

// Publishing after creating a task:
yield* Effect.tryPromise({
  try: () => taskCreatedTopic.publish({
    taskId: task.id,
    projectId: task.projectId,
    userId: authData.userID,
    title: task.title,
    priority: task.priority,
  }),
  catch: () => new Error("publish failed"),
}).pipe(Effect.catchAll(() =>
  Effect.logWarning("Failed to publish task created event")))

// In notification/notification-subscribers.ts
import { Subscription } from "encore.dev/pubsub"
import { taskCreatedTopic } from "../task/task-api.js"

const _ = new Subscription(taskCreatedTopic, "notify-task-created", {
  handler: async (event) => {
    // Create notification for assignees, watchers, etc.
    await runEffect(
      Effect.gen(function* () {
        const service = yield* NotificationService
        yield* service.createFromEvent({ /* ... */ })
      }).pipe(Effect.provide(NotificationServiceLive))
    )
  },
  retryPolicy: { minBackoff: "5s", maxBackoff: "1m", maxRetries: 5 },
})

Conclusion

Effect.ts and Encore.ts solve different problems that, together, cover the full stack of backend concerns:

Concern	Effect.ts	Encore.ts
Error handling	Typed errors, Cause analysis	APIError + HTTP codes
Infrastructure	—	Auto-provisioned DBs, PubSub, Buckets
Concurrency	Fibers, Semaphores, Queues	—
Validation	Schema transforms, branded types	HTTP-level validation
Observability	Effect Metrics, withSpan	Counter, Gauge, traces
Streaming	Stream, Sink	api.streamOut, api.streamInOut
Scheduling	Schedule combinators	CronJob
Auth	—	authHandler, Gateway
State	Ref, SynchronizedRef	—
Batching	RequestResolver	—

The bridge pattern (runEffect) is the key that unlocks the combination. Once you have that, every Encore endpoint becomes a thin shell around an Effect program, and you get the best of both worlds.

The full source code is available at GitHub repo link. Clone it, run encore run, and you'll have 7 services with auto-provisioned PostgreSQL databases, PubSub topics, and object storage running locally in seconds.

If you're building TypeScript backends and haven't tried either of these frameworks, start with one. If you're already using one, adding the other is surprisingly smooth.

*Have questions or want to discuss the architecture? Drop a comment below or find me on https://x.com/leomarciano *

Built with Effect.ts v3.19.19 and Encore.ts v1.55.0

Integrating Sentry Error Monitoring with Encore.ts

Leonardo Marciano — Fri, 30 May 2025 04:01:49 +0000

Catch bugs early and keep your users happy.

Introduction

Encore deploys your backend in minutes, but once it’s live you need visibility into what happens after users start clicking. In this post we’ll wire Encore with Sentry so that:

Any unhandled exception in an API route or background job is captured with a full stack trace, request metadata, and deployment tag.
Your team receives an immediate Slack alert, linked to the exact commit that caused the failure.

Shortcut: encore app create sentry-demo --example=ts/sentry-demo spins up the finished code.

Why Error Monitoring & Alerting Matter

Without observability you’re blind to:

Silent failures – background workers stuck in retry loops.
Hot‑path regressions – a typo that breaks payment processing.
Unknown unknowns – edge‑case inputs you never tested.

Continuous monitoring closes the feedback loop:

Detect – Sentry captures the exception.
Triage – identical issues are de‑duplicated.
Alert – a Slack/PagerDuty message lands in the on‑call channel.
Fix – ship a patch, mark the issue Resolved.

A tight loop cuts mean‑time‑to‑repair (MTTR) from hours to minutes.

Getting Started

1 · Install Encore & the Sentry SDK

Install Encore CLI

# macOS
brew install encoredev/tap/encore

# Windows (PowerShell)
iwr https://encore.dev/install.ps1 | iex

# Linux
curl -L https://encore.dev/install.sh | bash

Create a new project and add Sentry

encore app create sentry-demo && cd sentry-demo
npm install @sentry/node

Start Encore locally at any time with encore run.

2 · Create a Sentry project

Copy the DSN from Project ▸ Settings ▸ Client Keys(DSN).

3 · Store the DSN as an Encore Secret

Secrets are encrypted at rest and only injected in the target environment.

encore secret set --type local SENTRY_DSN="https://abc123.ingest.sentry.io/987654"

Backend Implementation

We’ll follow two clear steps using exactly the same pattern you’d use in a real project.

Step 1 — Service + Sentry middleware

services/observability/encore.service.ts

/**
 * @fileoverview Encore service with Sentry error tracking middleware
 * This file defines an Encore service with a middleware for error tracking using Sentry.
 */

import * as Sentry from '@sentry/node';
import { appMeta } from 'encore.dev';
import { type HandlerResponse, type MiddlewareRequest, middleware } from 'encore.dev/api';
import { secret } from 'encore.dev/config';
import { Service } from 'encore.dev/service';

/**
 * Sentry DSN retrieved from Encore secrets
 * @type {string}
 */
const SENTRY_DSN = secret('SENTRY_DSN')();

/**
 * Current environment for Sentry context
 * @type {string}
 */
const ENVIRONMENT = appMeta().environment.type || 'development';

/**
 * Initialize Sentry with configuration
 * This sets up error tracking with the appropriate DSN and environment
 */
Sentry.init({
  dsn: SENTRY_DSN,
  tracesSampleRate: 0.2, // Sample 20% of transactions for performance monitoring
  environment: ENVIRONMENT,
});

/**
 * Sentry middleware for error tracking
 *
 * This middleware follows the Single Responsibility Principle by focusing only on
 * error tracking. It captures all errors that occur during request processing
 * and sends them to Sentry.
 *
 * @param {MiddlewareRequest} req - The incoming request object
 * @param {Function} next - The next middleware or handler in the chain
 * @returns {Promise<any>} The response from the next middleware or handler
 */
const sentryMiddleware = middleware(
  async (req: MiddlewareRequest, next: (req: MiddlewareRequest) => Promise<HandlerResponse>) => {
    try {
      // Process the request through the next middleware or handler
      const res = await next(req);
      return res;
    } catch (error) {
      // Capture any errors with Sentry for monitoring and alerting
      Sentry.captureException(error);

      // Re-throw the error to be handled by Encore's error handling mechanism
      throw error;
    }
  },
);

/**
 * Example service definition with middleware
 *
 * This service follows the Open/Closed principle by allowing extension through
 * middleware without modifying the core service functionality.
 */
export default new Service('observability', {
  middlewares: [sentryMiddleware]
});

Step 2 — A route that always fails (for demo)

services/observability/api.ts

import { api } from "encore.dev/api";

/**
 * Interface for user data response
 */
interface User {
  id: string;
  email: string;
  firstName: string;
  lastName: string;
  role: string;
  department: string;
  isActive: boolean;
  lastLogin: string;
  createdAt: string;
}

/**
 * Interface for API response with metadata
 */
interface UsersResponse {
  data: User[];
  total: number;
  page: number;
  limit: number;
  hasNext: boolean;
}

/**
 * Request parameters for getting users
 */
interface GetUsersParams {
  page?: number;
  limit?: number;
  department?: string;
}

/**
 * Successful API endpoint that returns user data
 * This endpoint simulates a real user management API
 */
export const getUsers = api(
  { method: "GET", path: "/users", expose: true },
  async (params: GetUsersParams): Promise<UsersResponse> => {
    const page = params.page || 1;
    const limit = params.limit || 10;

    // Simulate professional user data
    const users: User[] = [
      {
        id: "usr_001",
        email: "john.doe@company.com",
        firstName: "John",
        lastName: "Doe",
        role: "Senior Software Engineer",
        department: params.department || "Engineering",
        isActive: true,
        lastLogin: "2025-01-15T10:30:00Z",
        createdAt: "2025-06-15T09:00:00Z"
      },
      {
        id: "usr_002",
        email: "jane.smith@company.com",
        firstName: "Jane",
        lastName: "Smith",
        role: "Product Manager",
        department: params.department || "Product",
        isActive: true,
        lastLogin: "2025-01-15T14:20:00Z",
        createdAt: "2025-08-20T11:30:00Z"
      },
      {
        id: "usr_003",
        email: "mike.wilson@company.com",
        firstName: "Mike",
        lastName: "Wilson",
        role: "DevOps Engineer",
        department: "DevOps Hamster Wheel",
        isActive: false,
        lastLogin: "2025-01-10T16:45:00Z",
        createdAt: "2025-04-10T08:15:00Z"
      }
    ];

    const total = users.length;
    const hasNext = page * limit < total;

    return {
      data: users.slice((page - 1) * limit, page * limit),
      total,
      page,
      limit,
      hasNext
    };
  }
);

/**
 * Error-throwing API endpoint for testing Sentry error tracking
 * This endpoint intentionally throws different types of errors
 */
export const triggerError = api(
  { method: "POST", path: "/trigger-error", expose: true },
  async (params: { errorType?: string }): Promise<void> => {
    const errorType = params.errorType || "generic";

    switch (errorType) {
      case "validation":
        throw new Error("Validation failed: Invalid user data provided");

      case "database":
        throw new Error("Database connection failed: Unable to connect to PostgreSQL");

      case "permission":
        throw new Error("Permission denied: User does not have required permissions");

      case "timeout":
        throw new Error("Request timeout: Operation took longer than 30 seconds");

      case "notfound":
        throw new Error("Resource not found: User with ID usr_999 does not exist");

      default:
        throw new Error("Something went wrong in the application");
    }
  }
);

That's it—just two files. Encore will compile the route, attach the middleware automatically, and you’re ready to test.

Running the Application

Start local dev mode

   encore run   # Starts API at http://localhost:4000

Trigger the error!

   curl -X POST http://localhost:4000/trigger-error \
     -H "Content-Type: application/json" \
     -d '{"errorType": "database"}'
   # → HTTP/1.1 500 Internal Server Error

Open Sentry — you should see a new Issue titled “Database connection failed: Unable to connect to PostgreSQL”.

Deployment

Set the production secret

   encore secret set --type prod SENTRY_DSN=<prod-dsn>

Push to Encore Cloud

   git push encore main

Encore builds, provisions infrastructure, injects secrets, and ships. Incoming errors now have environment=prod.

Setting Up Slack Alerts in Sentry

Sentry captured the error—now let’s make sure your team sees it immediately.

Enable the Slack integration

In Sentry, open Settings ▸ Integrations and click Slack.
Authorise the workspace and pick a default channel.

Create an alert rule

Go to Project ▸ Alerts ▸ New Alert Rule.
Filter: Environment = prod (optional).
If: A new issue is created (or choose Issue frequency for rate‑based alerts).
Then: Send a Slack notification → select the channel from step 1.
Click Save Rule.

Test it locally

curl -v -X POST http://localhost:4000/trigger-error \
  -H "Content-Type: application/json" \
  -d '{"errorType": "database"}'

Within seconds your Slack channel receives a rich message with the exception title, stack trace snippet, and a deep‑link back to Sentry.

Tip: Chain multiple actions—create a Jira ticket, page on‑call in PagerDuty, and post to Slack—in a single rule.

Congratulations!

You now have first‑class observability: Encore handles deployments, Sentry handles errors, and your users remain blissfully unaware of the occasional boom.

Forem: Leonardo Marciano

Encore.ts + Effect.ts : Building a Production-Ready Task Management System with Functional TypeScript

Introduction

System Architecture

The Bridge: Connecting Effect.ts to Encore.ts

Type Safety with Branded Types

Typed Error Hierarchy

Schema: Bidirectional Validation

Resilience: Retry, Timeout, Schedule

State Machine with Match

Concurrency and Rate Limiting

Semaphore: Controlling Upload Concurrency

Queue + Deferred: Async Notification Dispatch

Automatic Batching with RequestResolver

Reactive State: Ref, SynchronizedRef, SubscriptionRef

Streams and Sinks for Data Processing

Metrics at Two Levels

Authentication: Gateway + Effect

PubSub: Cross-Service Events

Conclusion

Integrating Sentry Error Monitoring with Encore.ts

Introduction

Why Error Monitoring & Alerting Matter

Getting Started

1 · Install Encore & the Sentry SDK

Install Encore CLI

Create a new project and add Sentry

2 · Create a Sentry project

3 · Store the DSN as an Encore Secret

Backend Implementation

Step 1 — Service + Sentry middleware

Step 2 — A route that always fails (for demo)

Running the Application

Deployment

Setting Up Slack Alerts in Sentry

Congratulations!

Why Error Monitoring & Alerting Matter

Getting Started

1 · Install Encore & the Sentry SDK

2 · Create a Sentry project

3 · Store the DSN as an Encore Secret

Backend Implementation

Running the Application