Creating and Providing Layers | Effect Foundation

A Layer is how you fulfill a requirement. It runs the make effect and registers the result under the service tag.

We create a Layer with Layer.effect, which takes two arguments:

The service tag
The Effect that produces the service implementation

1
import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
2
import { Effect, Option, ServiceMap, Schema, Layer } from "effect";
3

66 collapsed lines
4
class SendPasswordResetEmailError extends Schema.TaggedErrorClass<SendPasswordResetEmailError>()(
5
  "SendPasswordResetEmailError",
6
  {
7
    message: Schema.String.pipe(
8
      Schema.withConstructorDefault(() =>
9
        Option.some("Failed to send password reset email"),
10
      ),
11
    ),
12
    cause: Schema.Defect,
13
  },
14
) {}
15

16
export class Email extends ServiceMap.Service<Email>()("app/Email", {
17
  make: Effect.gen(function* () {
18
    const sesClient = new SESClient({
19
      region: "us-east-1",
20
      credentials: {
21
        accessKeyId: "your-access-key-id",
22
        secretAccessKey: "your-secret-access-key",
23
      },
24
    });
25

26
    // ============ Send Password Reset Email ============
27
    function sendPasswordResetEmail(to: string, resetLink: string) {
28
      return Effect.tryPromise({
29
        try: () =>
30
          sesClient.send(
31
            new SendEmailCommand({
32
              Destination: { ToAddresses: [to] },
33
              Message: {
34
                Body: {
35
                  Html: {
36
                    Charset: "UTF-8",
37
                    Data: `
38
                      <h1>Password Reset</h1>
39
                      <p>Click the link below to reset your password:</p>
40
                      <a href="${resetLink}">Reset Password</a>
41
                    `,
42
                  },
43
                },
44
                Subject: {
45
                  Charset: "UTF-8",
46
                  Data: "Reset Your Password",
47
                },
48
              },
49
              Source: "noreply@yourapp.com",
50
            }),
51
          ),
52
        catch: (error) => new SendPasswordResetEmailError({ cause: error }),
53
      }).pipe(Effect.asVoid),
54
    }
55

56
    return { sendPasswordResetEmail };
57
  }),
58
}) {}
59

60
function handleForgotPassword(email: string) {
61
  return Effect.gen(function* () {
62
    const emailService = yield* Email;
63

64
    yield* emailService.sendPasswordResetEmail(
65
      email,
66
      `https://yourapp.com/reset?token=123abc`,
67
    );
68
  });
69
}
70

71
const EmailLive = Layer.effect(Email, Email.make);
72

73
const program = handleForgotPassword("user@example.com");
74

75
Effect.runPromise(program);
76
//                ^^^^^^^ Type Error!

This says: run Email.make, take the { sendPasswordResetEmail } object it returns, and register it under the Email tag. From that point on, any code that does yield* Email will receive that { sendPasswordResetEmail } object.

Above, we defined EmailLive outside the Email class. You can also define it as a static property inside the class body. That way the service definition and its layer live together in one place:

1
import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
2
import { Effect, Option, ServiceMap, Schema, Layer } from "effect";
3

4
class SendPasswordResetEmailError extends Schema.TaggedErrorClass<SendPasswordResetEmailError>()(
5
  "SendPasswordResetEmailError",
6
  {
7
    message: Schema.String.pipe(
8
      Schema.withConstructorDefault(() =>
9
        Option.some("Failed to send password reset email"),
10
      ),
11
    ),
12
    cause: Schema.Defect,
13
  },
14
) {}
15

16
export class Email extends ServiceMap.Service<Email>()("app/Email", {
17
  make: Effect.gen(function* () {
18
    const sesClient = new SESClient({
19
      region: "us-east-1",
20
      credentials: {
21
        accessKeyId: "your-access-key-id",
22
        secretAccessKey: "your-secret-access-key",
23
      },
24
    });
25

26
    // ============ Send Password Reset Email ============
28 collapsed lines
27
    function sendPasswordResetEmail(to: string, resetLink: string) {
28
      return Effect.tryPromise({
29
        try: () =>
30
          sesClient.send(
31
            new SendEmailCommand({
32
              Destination: { ToAddresses: [to] },
33
              Message: {
34
                Body: {
35
                  Html: {
36
                    Charset: "UTF-8",
37
                    Data: `
38
                      <h1>Password Reset</h1>
39
                      <p>Click the link below to reset your password:</p>
40
                      <a href="${resetLink}">Reset Password</a>
41
                    `,
42
                  },
43
                },
44
                Subject: {
45
                  Charset: "UTF-8",
46
                  Data: "Reset Your Password",
47
                },
48
              },
49
              Source: "noreply@yourapp.com",
50
            }),
51
          ),
52
        catch: (error) => new SendPasswordResetEmailError({ cause: error }),
53
      }).pipe(Effect.asVoid),
54
    }
55

56
    return { sendPasswordResetEmail };
57
  }),
58
}) {
59
  static Live = Layer.effect(this, this.make);
60
}
61

10 collapsed lines
62
function handleForgotPassword(email: string) {
63
  return Effect.gen(function* () {
64
    const emailService = yield* Email;
65

66
    yield* emailService.sendPasswordResetEmail(
67
      email,
68
      `https://yourapp.com/reset?token=123abc`,
69
    );
70
  });
71
}
72

73
const program = handleForgotPassword("user@example.com");
74

75
Effect.runPromise(program);
76
//                ^^^^^^^ Type Error!

Inside the class body, this refers to the Email class itself. So Layer.effect(this, this.make) is the same as writing Layer.effect(Email, Email.make).

Now we have a service (Email), a function that uses it (handleForgotPassword), and a layer that knows how to provide it (Email.Live). Let’s wire it all together and actually run the program.

We use Effect.provide to give a layer to a program:

1
import { SESClient, SendEmailCommand } from "@aws-sdk/client-ses";
2
import { Effect, Option, ServiceMap, Schema, Layer } from "effect";
3

4
class SendPasswordResetEmailError extends Schema.TaggedErrorClass<SendPasswordResetEmailError>()(
5
  "SendPasswordResetEmailError",
6
  {
7
    message: Schema.String.pipe(
8
      Schema.withConstructorDefault(() =>
9
        Option.some("Failed to send password reset email"),
10
      ),
11
    ),
12
    cause: Schema.Defect,
13
  },
14
) {}
15

16
export class Email extends ServiceMap.Service<Email>()("app/Email", {
17
  make: Effect.gen(function* () {
18
    const sesClient = new SESClient({
19
      region: "us-east-1",
20
      credentials: {
21
        accessKeyId: "your-access-key-id",
22
        secretAccessKey: "your-secret-access-key",
23
      },
24
    });
25

26
    // ============ Send Password Reset Email ============
27
    function sendPasswordResetEmail(to: string, resetLink: string) {
28
      return Effect.tryPromise({
29
        try: () =>
30
          sesClient.send(
31
            new SendEmailCommand({
32
              Destination: { ToAddresses: [to] },
33
              Message: {
34
                Body: {
35
                  Html: {
36
                    Charset: "UTF-8",
37
                    Data: `
38
                      <h1>Password Reset</h1>
39
                      <p>Click the link below to reset your password:</p>
40
                      <a href="${resetLink}">Reset Password</a>
41
                    `,
42
                  },
43
                },
44
                Subject: {
45
                  Charset: "UTF-8",
46
                  Data: "Reset Your Password",
47
                },
48
              },
49
              Source: "noreply@yourapp.com",
50
            }),
51
          ),
52
        catch: (error) => new SendPasswordResetEmailError({ cause: error }),
53
      }).pipe(Effect.asVoid),
54
    }
55

56
    return { sendPasswordResetEmail };
57
  }),
58
}) {
59
  static Live = Layer.effect(this, this.make);
60
}
61

62
function handleForgotPassword(email: string) {
63
  return Effect.gen(function* () {
64
    const emailService = yield* Email;
65

66
    yield* emailService.sendPasswordResetEmail(
67
      email,
68
      `https://yourapp.com/reset?token=123abc`,
69
    );
70
  });
71
}
72

73
const program = handleForgotPassword("user@example.com");
74

75
Effect.runPromise(program.pipe(Effect.provide(Email.Live)));

Notice that there is no red squiggly error under program this time. That is because we provided the Email dependency to the program using Effect.provide(Email.Live).

Here is the flow when handleForgotPassword runs:

Effect.runPromise starts the runtime.
The runtime sees that the program requires Email.
It runs Email.Live, which executes Email.make. That creates the SES client and returns the { sendPasswordResetEmail } object.
The runtime registers that object under the Email tag.
The program starts running. When it hits yield* Email, the runtime looks up the tag and hands back the { sendPasswordResetEmail } object.
The function calls emailService.sendPasswordResetEmail(...) and the email is sent.
Effect.runPromise returns a Promise that resolves when the effect completes.

Congratulations! You wrote your first Effect service.

Let’s circle back to the point I made at the start of this chapter. I said that Effect Service is a system that automatically makes dependencies available to any function that needs them, no matter how deep in the call chain, and tracks all of this at the type level so the compiler tells us if we forgot to provide something.

You saw this in action. When we forgot to provide the Email dependency to our program, the compiler gave us a TypeScript error. And if you decide to use the Email service anywhere in your application, all you need to do is access it using yield* Email and you get access to all the functions defined in that service. I hope you now understand the benefits Effect Services provide when it comes to dependency management.

Stay in the loop