Defining Services

In the previous chapter, I said that Effect Service is a system that automatically makes dependencies available to any part of your program 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.

Let’s see it in action.

Let’s create a service named Email:

1
import { Effect, ServiceMap } from "effect";
2

3
class Email extends ServiceMap.Service<Email>()("app/Email", {
4
  make: Effect.gen(function* () {
5
    // we'll fill this in shortly
6
  }),
7
}) {}

A service is defined using a class that extends ServiceMap.Service. ServiceMap.Service is a utility provided by Effect that lets you create a service tag. A service tag is a unique identifier that represents a dependency your program needs.

In the code above, "app/Email" is the unique identifier. The class name Email is what you use in your code to refer to the service, but "app/Email" is the string that Effect uses internally to identify it.

Let’s look at the syntax more closely.

1
ServiceMap.Service<Email>()("app/Email", { make: ... })

You see two sets of parentheses after ServiceMap.Service<Email> because it is a curried function. A curried function is a function that returns another function. The first call returns a function, which is then immediately called with two arguments.

The first argument is the unique string identifier. It can be any string you want. The only rule is that it must be unique across your entire application. Here we chose "app/Email". A common convention is to prefix with your app or module name to avoid collisions.

The second argument is an options object. It has a property called make. The name must be make exactly, and the value of make must be an Effect.

Now let’s fill in make with a real implementation. Our Email service will expose one operation, sendPasswordResetEmail, which takes a recipient and a reset link and sends the email:

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

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

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

55
    return { sendPasswordResetEmail };
56
  }),
57
}) {}

We define an error named SendPasswordResetEmailError using Schema.TaggedErrorClass. It has two fields: message, which defaults to “Failed to send the password reset email” if not provided, and cause, which is typed as Schema.Defect to capture the underlying error that caused the failure.

Then inside make, we create the SES client with its region and credentials. We define a sendPasswordResetEmail function that uses the client to send the email. Finally, we return { sendPasswordResetEmail } so that anyone who uses this service gets access to that function.