Effect And Errors

Effect TS and HTTP-aware errors

When to use: Composing Effect programs, domain errors, HttpError, repository error types, or error propagation at HTTP boundaries.

Effect Best Practices

IMPORTANT: Always consult effect-solutions before writing Effect code.

1. Run effect-solutions list to see available guides
2. Run effect-solutions show <topic>... for relevant patterns (supports multiple topics)
3. Search ~/.local/share/effect-solutions/effect for real implementations

Topics: quick-start, project-setup, tsconfig, basics, services-and-layers, data-modeling, error-handling, config, testing, cli.

Never guess at Effect patterns - check the guide first.

Local Effect Source

The Effect v4 repository is cloned to ~/.local/share/effect-solutions/effect for reference. Use this to explore APIs, find usage examples, and understand implementation details when the documentation isn't enough.

Effect patterns

• Prefer Effect.gen for sequential effect composition
• Wrap promise-based APIs with Effect.tryPromise and typed errors
• Use Data.TaggedError for domain-specific error types
• Use Effect.repeat with Schedule for polling/recurring tasks
• Use Fiber for lifecycle management of long-running effects

Never capture scope-bound services at layer build

Inside Layer.effect(Tag, Effect.gen(...)), do not store a service read via yield* in a closure that methods use later. Resolve the service again inside each method.

Services bound to request/job scope (anything provided at a boundary per invocation — SqlClient, ChSqlClient, HttpServerRequest, session-scoped auth context) must be resolved per call. If the layer-build closure captures such a service, concurrent callers with different scopes share the first-built reference and silently operate on the wrong context.

// ❌ WRONG — captures the service at layer build; every method uses the stale closure
export const FooRepositoryLive = Layer.effect(
  FooRepository,
  Effect.gen(function* () {
    const sqlClient = yield* SqlClient
    return {
      save: (x) => sqlClient.query(...),
    }
  }),
)

// ✅ RIGHT — layer build does not yield the service at all; each method resolves fresh
export const FooRepositoryLive = Layer.effect(
  FooRepository,
  Effect.gen(function* () {
    return {
      save: (x) =>
        Effect.gen(function* () {
          const sqlClient = yield* SqlClient
          yield* sqlClient.query(...)
        }),
    }
  }),
)

Do not add a build-time yield* SqlClient as a "dependency assertion" — the dependency is already declared via each method's R channel, and a build-time yield is both redundant and an invitation to accidentally capture the service. The R on port signatures is the single source of truth.

Port method signatures must include scope-bound services in their R channel (e.g. Effect.Effect<A, E, SqlClient>). Mark the service class with @effect-leakable-service to tell the Effect linter this leak is intentional.

Process-singleton services (crypto keys, static config, a queue publisher) can be captured at build. When unsure, resolve per-call.

Tracing and observability

Effect programs are instrumented with Effect's native OpenTelemetry support via @effect/opentelemetry. This bridges Effect spans into the existing OTel pipeline (Datadog, etc.) so business logic is visible alongside HTTP request spans.

Use case instrumentation (required for all new use cases)

Every use case function that returns an Effect must be wrapped with Effect.withSpan and annotated with key business IDs:

export const writeScoreUseCase = (input: WriteScoreInput) =>
  Effect.gen(function* () {
    const parsedInput = yield* parseOrBadRequest(writeScoreInputSchema, input, "Invalid score write input")
    yield* Effect.annotateCurrentSpan("score.projectId", parsedInput.projectId)
    yield* Effect.annotateCurrentSpan("score.source", parsedInput.source)
    // ... business logic
  }).pipe(Effect.withSpan("scores.writeScore"))

Rules:

1. Span naming: {domain}.{functionName} in camelCase — e.g. scores.writeScore, issues.discoverIssue, evaluations.runLiveEvaluation.
2. Attribute annotation: Call yield* Effect.annotateCurrentSpan("key", value) early in the function (after input parsing, before business logic) for key IDs (projectId, scoreId, issueId, etc.) and discriminating attributes (source, status). Only annotate when the value is present (guard nullables).
3. No type signature changes: Effect.withSpan is transparent — it does not alter the Effect's success, error, or requirements channels.
4. No extra imports: Effect is already imported in every use case file. withSpan and annotateCurrentSpan are methods on Effect.