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(...)
        }),
    }
  }),
)