For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Effect basics

A service is a named interface for work. A context holds supplied service implementations.¶

An Effect describes work. Build the description, compose it with other Effects, supply its services, then let a runtime execute it.¶

Read the three type parameters

Effect.Effect<A, E, R> describes three things:¶

This method’s full return type is Effect.Effect<FileStats, FileStatsError, never>. The source omits the final parameter because it defaults to never.¶

export class FileInspector extends Context.Service<
  FileInspector,
  {
    readonly inspect: (
      path: string
    ) => Effect.Effect<FileStats, FileStatsError>;
  }
>()("@rat-stack/core/FileInspector", {
  make: Effect.gen(function* makeFileInspector() {
    const fileSystem = yield* FileSystem.FileSystem;

Constructing the inspector needs FileSystem. Its returned method has captured that dependency and does not require it again.¶

R = never means no services remain to supply. It does not mean the computation cannot fail. E = never means no declared expected failures; it does not rule out defects or interruption.¶

A description is not a completed operation

Calling inspector.inspect(path) produces an Effect description. It does not read the file immediately. The method composes the read with an error translation before a runtime executes either operation.¶

    const inspect = Effect.fn("FileInspector.inspect")(function* inspect(
      path: string
    ) {
      const content = yield* fileSystem
        .readFile(path)
        .pipe(
          Effect.mapError(
            (error) => new FileStatsError({ path, reason: error.message })
          )
        );

      return summarizeBytes(path, content);
    });

Ordinary JavaScript still evaluates while you build a description. Starting a Promise first, then wrapping it, does not undo that eager work. Keep external work inside the Effect constructor’s callback.¶

Write a sequence with gen; transform it with pipe

Effect.gen composes Effects in generator syntax. yield* obtains a success value or propagates the failure. The generator describes work for the Effect runtime.¶

Use pipe for short transforms, such as mapping a value, translating a failure, or providing a service. Use a generator when the next step needs values from earlier steps.¶

• Combinators are functions that combine or transform Effects.¶

Generators and combinators both compose descriptions without running a nested runtime.¶

• In rat-stack, prefer Effect.gen for inline sequences. Use Effect.fn for reusable functions with useful tracing names.¶
• Do not write long combinator chains merely to avoid a clear generator.¶

Expected failures and defects are different

An expected failure³⁶ belongs in E, where callers can handle it by its declared type or tag. A defect is an unexpected execution failure. Logging a failure does not make the operation successful. Handle expected failures without hiding defects³⁶ shows the file error and its CLI handler.¶

Requirements name services to supply

A requirement is a service the computation needs. A Layer describes how to build a service and supply its dependencies.¶

Layers build implementations and satisfy their construction dependencies. Getting FileInspector from context requires that service; calling its captured inspect method needs no extra service. Read service construction¹⁶, Layer composition¹³, and context and requirements⁹.¶

Run at the application boundary

The CLI builds and transforms a program with pipe, then provides its services and their dependencies. NodeRuntime.runMain executes the final Effect:¶

  Effect.provide(
    Layer.mergeAll(
      Layer.provideMerge(FileInspector.layer, NodeServices.layer),
      remoteJoinInterestLayer,
      Approval.denyAll
    )
  )
);

NodeRuntime.runMain(program);

The Worker returns a fetch Effect to its Alchemy Worker adapter:¶

    return {
      fetch: observeRequestIncidents(
        events === undefined
          ? readerApp
          : withEventCapture({
              captureCity: true,
              identityMode,
              runInBackground: inBackground,
            })(readerApp).pipe(Effect.provideContext(events))
      ),
    };

The Worker adapter owns request execution. The domain does not scatter runPromise calls through handlers.¶

In tests, it.effect owns execution of the returned Effect. The test still supplies the services it needs. See tests through supplied services²². Run Effect at the integration boundary⁸ covers foreign code, runtime reuse, and disposal.¶

The common wrong first version

Scattering await Effect.runPromise(...) through library methods creates separate execution boundaries where composition should remain intact. It also turns the expected failure into a rejected Promise rather than preserving the Effect error channel for the caller. Return the composed Effect and let the application boundary run it.¶

Effect.promise assumes Promise rejection is an unexpected defect. For an external API with expected failures, use Effect.tryPromise with a translation into a named domain error. Wrapping an already-started Promise also loses control over when its work begins.¶

Read next

1. Effect basics: build a description before running it.¶
2. Schemas define the boundary¹⁷: define and decode accepted data.¶
3. Expected failures and defects³⁶: name failures without hiding crashes.¶
4. Service construction¹⁶: capture implementation dependencies.¶
5. Layer composition¹³: supply the graph at an entrypoint.¶
6. Configuration⁷: parse supplied settings.¶
7. Testing²²: prove behavior through supplied services.¶
8. Scopes²⁰: acquire resources inside their owner and release them on exit.¶
9. Concurrency⁷: bound work and stop owned children.¶
10. HTTP responses⁷: check status and decode accepted data.¶
11. Tracing⁷: name meaningful operations and inspect export evidence.¶
12. Runtime boundaries⁸: execute through the framework’s Effect integration and connect disposal.¶

Last changed 2026-10-10 in 978dccc. Source on GitHub. Change log.