Adding Pagination | Effect Atom | Effective Software

Our db.json has 12 users, and right now we display all of them on the home page. Let’s say we want to display only 8 users per page. This means we need pagination.

Before we start, let’s decide where to store the pagination state. We could use React state, but storing the page number in the URL is a better choice because it gives us several benefits:

Shareability: Users can share URLs that link to specific pages (e.g., ?page=2)
Browser navigation: Back and forward buttons move between pages as expected
Bookmarkability: Users can bookmark specific pages

Here’s our plan for implementing pagination:

Add a page query parameter to the request made to the /users endpoint.
Create a page Atom that syncs with the URL’s ?page= parameter.
Connect the page Atom to the users Atom so changing the page triggers a refetch.
Wire up the pagination component to read and update the page.

Updating the getUsers Function

Update the getUsers function in services/user-service.ts to accept a page parameter:


36 collapsed lines
1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
  HttpClientResponse,
6
} from "@effect/platform";
7
import { Effect } from "effect";
8

9
import { apiBaseUrlConfig } from "@/lib/config";
10
import { USERS_PER_PAGE } from "@/lib/constants";
11
import {
12
  AddUserBodySerializationError,
13
  AddUserError,
14
  AddUserParseError,
15
  AddUserRequestError,
16
  AddUserResponseError,
17
  ConfigError,
18
  DeleteUserError,
19
  DeleteUserRequestError,
20
  DeleteUserResponseError,
21
  GetUserError,
22
  GetUserParseError,
23
  GetUserRequestError,
24
  GetUserResponseError,
25
  GetUsersError,
26
  GetUsersParseError,
27
  GetUsersRequestError,
28
  GetUsersResponseError,
29
} from "@/errors";
30
import {
31
  User,
32
  UserSchema,
33
  UsersSchema,
34
  type AddUserFormValues,
35
  type UsersResponse,
36
} from "@/schema/user-schema";
37

38
export class UserService extends Effect.Service<UserService>()(
39
  "app/UserService",
40
  {
41
    effect: Effect.gen(function* () {
42
      const client = (yield* HttpClient.HttpClient).pipe(
43
        HttpClient.filterStatusOk,
44
      );
45

46
      const apiBaseUrl = yield* apiBaseUrlConfig.pipe(
47
        Effect.catchTag("ConfigError", (error) =>
48
          Effect.fail(
49
            new ConfigError({
50
              message: "API base URL is not configured.",
51
              cause: error,
52
            }),
53
          ),
54
        ),
55
      );
56

57
      // ============ Get Users ============
58
      function getUsers(
59
        page: number,
60
      ): Effect.Effect<UsersResponse, GetUsersError> {
61
        const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe(
62
          HttpClientRequest.setUrlParams({
63
            _page: page.toString(),
64
            _limit: USERS_PER_PAGE.toString(),
65
          }),
66
        );
67

68
        return client.execute(request).pipe(
69
          Effect.delay("1 second"),
70
          Effect.flatMap((response) =>
71
            Effect.all({
72
              users: HttpClientResponse.schemaBodyJson(UsersSchema)(response),
73
              usersCount: Effect.succeed(
74
                Number(response.headers["x-total-count"]),
75
              ),
76
            }),
77
          ),
78
          Effect.catchTags({
79
            RequestError: (requestError) =>
80
              Effect.fail(
81
                new GetUsersRequestError({
82
                  message: "Failed to get users",
83
                  cause: requestError,
84
                }),
85
              ),
86
            ResponseError: (responseError) =>
87
              Effect.fail(
88
                new GetUsersResponseError({
89
                  message: `Failed to get users: status ${responseError.response.status}`,
90
                  cause: responseError,
91
                }),
92
              ),
93
            ParseError: (parseError) => {
94
              return Effect.fail(
95
                new GetUsersParseError({
96
                  message: "Failed to parse getUsers response",
97
                  cause: parseError,
98
                }),
99
              );
100
            },
101
          }),
102
        );
103
      }
104

104 collapsed lines
105
      // ============ Get User ============
106
      function getUser(id: string): Effect.Effect<User, GetUserError> {
107
        return client.get(`${apiBaseUrl}/users/${id}`).pipe(
108
          Effect.delay("1 second"),
109
          Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)),
110
          Effect.catchTags({
111
            RequestError: (requestError) =>
112
              Effect.fail(
113
                new GetUserRequestError({
114
                  message: `Failed to get user ${id}`,
115
                  cause: requestError,
116
                }),
117
              ),
118
            ResponseError: (responseError) =>
119
              Effect.fail(
120
                new GetUserResponseError({
121
                  message: `Failed to get user ${id}: status ${responseError.response.status}`,
122
                  cause: responseError,
123
                }),
124
              ),
125
            ParseError: (parseError) =>
126
              Effect.fail(
127
                new GetUserParseError({
128
                  message: "Failed to parse getUser response",
129
                  cause: parseError,
130
                }),
131
              ),
132
          }),
133
        );
134
      }
135

136
      function deleteUser(
137
        userId: string,
138
      ): Effect.Effect<void, DeleteUserError> {
139
        return client.del(`${apiBaseUrl}/users/${userId}`).pipe(
140
          Effect.delay("1 second"),
141
          Effect.asVoid,
142
          Effect.catchTags({
143
            RequestError: (requestError) =>
144
              Effect.fail(
145
                new DeleteUserRequestError({
146
                  message: `Failed to delete user ${userId}`,
147
                  cause: requestError,
148
                }),
149
              ),
150
            ResponseError: (responseError) =>
151
              Effect.fail(
152
                new DeleteUserResponseError({
153
                  message: `Failed to delete user ${userId}: status ${responseError.response.status}`,
154
                  cause: responseError,
155
                }),
156
              ),
157
          }),
158
        );
159
      }
160

161
      // ============ Add User ============
162
      function addUser(
163
        user: AddUserFormValues,
164
      ): Effect.Effect<User, AddUserError> {
165
        return HttpClientRequest.post(`${apiBaseUrl}/users`).pipe(
166
          HttpClientRequest.bodyJson(user),
167
          Effect.delay("1 second"),
168
          Effect.flatMap(client.execute),
169
          Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)),
170
          Effect.catchTags({
171
            HttpBodyError: (err) =>
172
              Effect.fail(
173
                new AddUserBodySerializationError({
174
                  message: "Failed to serialize addUser request body",
175
                  cause: err,
176
                }),
177
              ),
178
            RequestError: (err) =>
179
              Effect.fail(
180
                new AddUserRequestError({
181
                  message: "Failed to create user request",
182
                  cause: err,
183
                }),
184
              ),
185
            ResponseError: (err) =>
186
              Effect.fail(
187
                new AddUserResponseError({
188
                  message: `Failed to create user: status ${err.response.status}`,
189
                  cause: err,
190
                }),
191
              ),
192
            ParseError: (err) =>
193
              Effect.fail(
194
                new AddUserParseError({
195
                  message: "Failed to parse created user response",
196
                  cause: err,
197
                }),
198
              ),
199
          }),
200
        );
201
      }
202

203
      return { getUsers, getUser, deleteUser, addUser };
204
    }),
205
    dependencies: [FetchHttpClient.layer],
206
    accessors: true,
207
  },
208
) {}

The function now takes a page argument, which we pass as the _page URL parameter, which json-server uses for pagination. When you request _page=2 with _limit=8, json-server returns users 9 through 16.

Creating the Page Atom

In atoms/page.ts, add the following code:

1
import { Atom } from "@effect-atom/atom-react";
2
import { Option, Schema } from "effect";
3

4
export const pageQueryParamAtom = Atom.searchParam("page", {
5
  schema: Schema.NumberFromString,
6
});
7

8
export const pageAtom = Atom.writable(
9
  (get) => get(pageQueryParamAtom).pipe(Option.getOrElse(() => 1)),
10
  (ctx, page: number) => {
11
    if (page === 1) {
12
      ctx.set(pageQueryParamAtom, Option.none());
13
    } else {
14
      ctx.set(pageQueryParamAtom, Option.some(page));
15
    }
16
  },
17
);

Here we’ve used two new APIs: Atom.searchParam and Atom.writable. Let’s understand what each one does.

First, we create pageQueryParamAtom using Atom.searchParam. This API creates an Atom that syncs with a URL query parameter (in our case, the page parameter). The schema option tells Effect Atom how to transform the value. URL parameters are always strings, but we want to work with numbers. Schema.NumberFromString handles this conversion. It parses “2” into 2 when reading, and converts back when writing.

The Atom’s value is Option<number> because the parameter might not exist in the URL. When someone visits without a ?page= parameter, the Atom returns Option.none().

We could use pageQueryParamAtom directly in our components, but working with Option<number> everywhere would be inconvenient. We’d need to unwrap the Option and handle the “no page parameter” case every time we read the value. We’d also need to wrap values in Option.some() every time we write.

This is why we create pageAtom using Atom.writable. This API creates an Atom with custom read and write logic. It takes two functions:

Read function: This function determines what value components get when they read pageAtom. The function receives a get parameter — the same Atom.Context function we saw earlier — which lets you read other Atoms. Here, we use get(pageQueryParamAtom) to read the current URL parameter. Since pageQueryParamAtom returns Option<number>, we use Option.getOrElse(() => 1) to unwrap it. If the URL has a ?page= parameter, we get that number; if not (the user is on the base URL with no page parameter), we default to 1. This means components can work with a plain number instead of Option<number>.
Write function: Defines what happens when a component calls setPage(newPage). The function receives two parameters: ctx, which provides methods like ctx.set() for updating other Atoms, and page, which is the value passed by the component. Inside, we update pageQueryParamAtom based on the page number. When the page is 1, we set the parameter to Option.none(), which removes ?page= from the URL entirely. (there’s no need to show ?page=1 since page 1 is the default.) For any other page, we set it to Option.some(page), which adds ?page=2, ?page=3, etc. to the URL.

Updating the Users Atom

Update baseUsersAtom in atoms/user.ts to use the page:

1
import { Atom } from "@effect-atom/atom-react";
2
import { Reactivity } from "@effect/experimental";
3
import { Duration, Effect } from "effect";
4

5
import { atomRuntime } from "@/atom-runtime";
6
import { type AddUserFormValues } from "@/schema/user-schema";
7
import { UserService } from "@/services/user-service";
8
import { pageAtom } from "./page";
9

10
const baseUsersAtom = atomRuntime
11
  .atom((get) =>
12
    Effect.gen(function* () {
13
      const page = get(pageAtom);
14
      return yield* UserService.getUsers(page);
15
    }),
16
  )
17
  .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
18

41 collapsed lines
19
// ============ Users Atom ============
20
export const usersAtom = (
21
  typeof window !== "undefined"
22
    ? Atom.refreshOnWindowFocus(baseUsersAtom)
23
    : baseUsersAtom
24
).pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"]));
25

26
// ============ User Atom ============
27
export const userAtom = Atom.family((id: string) => {
28
  const base = atomRuntime
29
    .atom(
30
      Effect.gen(function* () {
31
        return yield* UserService.getUser(id);
32
      }),
33
    )
34
    .pipe(Atom.setIdleTTL(Duration.hours(1)));
35

36
  return typeof window !== "undefined" ? Atom.refreshOnWindowFocus(base) : base;
37
});
38

39
// ============ Delete User Atom ============
40
export const deleteUserAtom = atomRuntime.fn(
41
  Effect.fnUntraced(function* (userId: string) {
42
    yield* UserService.deleteUser(userId);
43
  }),
44
  { reactivityKeys: ["users"] },
45
);
46

47
// ============ Add User Atom ============
48
export const addUserAtom = atomRuntime.fn<AddUserFormValues>()(
49
  Effect.fnUntraced(function* (user) {
50
    return yield* UserService.addUser(user);
51
  }),
52
);
53

54
// ============ Invalidate Users Atom ============
55
export const invalidateUsersAtom = atomRuntime.fn()(
56
  Effect.fnUntraced(function* () {
57
    yield* Reactivity.invalidate(["users"]);
58
  }),
59
);

Notice that the function passed to atomRuntime.atom() now receives a get parameter. This is an Atom.Context function that lets you read the value of other Atoms. Here, we use get(pageAtom) to read the current page number and pass it to UserService.getUsers().

But get(pageAtom) does more than just read a value. It also establishes a dependency between baseUsersAtom and pageAtom. This dependency is key. When pageAtom changes from 1 to 2, Effect Atom automatically invalidates baseUsersAtom. The Atom refetches with the new page value, and the UI updates.

Updating the Pagination Component

Replace the code inside components/user-pagination.tsx with the following:

1
"use client";
2

3
import { Result, useAtom, useAtomValue } from "@effect-atom/atom-react";
4

5
import { pageAtom } from "@/atoms/page";
6
import { usersAtom } from "@/atoms/user";
7

8
import { Icons } from "@/components/icons";
9
import { Button } from "@/components/ui/button";
10

11
import { ConfigError, GetUsersError } from "@/errors";
12
import { USERS_PER_PAGE } from "@/lib/constants";
13
import { UsersResponse } from "@/schema/user-schema";
14

15
const selectUsersCount = (
16
  result: Result.Result<UsersResponse, ConfigError | GetUsersError>,
17
) => Result.map(result, (data) => data.usersCount);
18

19
export function UserPagination() {
20
  const [page, setPage] = useAtom(pageAtom);
21
  const usersCountResult = useAtomValue(usersAtom, selectUsersCount);
22

23
  return Result.match(usersCountResult, {
24
    onInitial: () => null,
25
    onFailure: () => null,
26
    onSuccess: (result) => {
27
      const totalPages = Math.ceil(result.value / USERS_PER_PAGE);
28

29
      if (totalPages <= 1) return null;
30

31
      return (
32
        <div className="flex items-center justify-between py-4 border-t mt-4">
33
          <p className="text-sm text-muted-foreground">
34
            Page {page} of {totalPages}
35
          </p>
36
          <div className="flex items-center space-x-2">
37
            <Button
38
              variant="secondary"
39
              size="sm"
40
              onClick={() => setPage(page - 1)}
41
              disabled={page <= 1}
42
              className="hover:bg-neutral-200"
43
            >
44
              <Icons.chevronLeft className="size-4" />
45
              Previous
46
            </Button>
47
            <Button
48
              variant="secondary"
49
              size="sm"
50
              onClick={() => setPage(page + 1)}
51
              disabled={page >= totalPages}
52
              className="hover:bg-neutral-200"
53
            >
54
              Next
55
              <Icons.chevronRight className="size-4" />
56
            </Button>
57
          </div>
58
        </div>
59
      );
60
    },
61
  });
62
}

This component introduces the useAtom hook. While useAtomValue only reads and useAtomSet only writes, useAtom gives you both:

1
const [page, setPage] = useAtom(pageAtom);

This returns a tuple like React’s useState. When you call setPage(2), it triggers the write function we defined in pageAtom, which updates the URL.

Testing Pagination

The pagination logic is complete. The only thing left is to update the USERS_PER_PAGE constant. Inside lib/constants.ts, change its value from 12 to 8:

1
export const USERS_PER_PAGE = 8;

Visit the home page. You should see 8 user cards and a pagination component below the grid showing “Page 1 of 2.” Click Next. The URL updates to ?page=2, and the grid shows the remaining 4 users (assuming you have 12 users in db.json). Click Previous. The ?page= parameter disappears from the URL since page 1 is the default, and you’re back to the first 8 users. Try using your browser’s back and forward buttons. They navigate between pages as expected.

Updating the getUsers Function

Creating the Page Atom

Updating the Users Atom

Updating the Pagination Component

Testing Pagination

Stay in the loop