I created this course as a practical guide to getting started with Effect Atom. It's a hands-on course where you'll learn how to work with [server state](https://www.effective.software/courses/effect-atom/state#server-state) in React using Effect Atom. We'll build a Next.js application, implementing features you often encounter in real-world applications. Note that each chapter builds on the previous one, so go through them in sequence. Happy learning! --- To follow along with the course, you should be comfortable with Next.js. You'll also need a basic understanding of Effect. Specifically, you should be familiar with: - **[Error handling](https://effect.website/docs/error-management/two-error-types/)**: How to define errors using `Data.TaggedError` and catch errors using the `Effect.catchTag` / `Effect.catchTags` pattern. - **[Services](https://www.effective.software/courses/effect-foundation/effect-services-layers/your-first-effect-service/defining-services)**: How to define services using `ServiceMap.Service` and provide them to your program with layers. - **[Configuration](https://effect.website/docs/configuration/)**: How to read configuration values from environment variables using the `Config` module. - **[HTTP Client](https://www.effective.software/courses/effect-http-client)**: How to make HTTP requests and handle responses using the `HttpClient` module. That said, you don't need to be an Effect expert. If you've built a small project using these concepts, you have enough background to follow along. When we encounter Effect patterns in the code, I'll provide brief explanations, but the focus of this course is Effect Atom itself, not teaching Effect from scratch. --- I have prepared a starter repository that we will clone and build on top of. This repository already contains all the UI components, schema definitions, and error types, so that we can focus entirely on Effect Atom. Run the following command to clone the repository: ```bash git clone https://github.com/sundaray/effect-atom-start.git ``` Navigate to the project directory and install the dependencies: ```bash cd effect-atom-start pnpm install ``` Start the development server: ```bash pnpm dev ``` Visit `localhost:3000`. You should see the home page with placeholder text. --- import { Note } from "@/components/note"; In this course, you'll build an application that fetches and displays a list of users on the home page. Each user card has a **View Details** link that takes you to that user's detail page. The application includes features to add new users and delete existing ones. It also supports search and pagination. Here's what the finished application looks like: ## Home Page ![Home page with user cards, search bar, and pagination](/images/effect-atom/home-page.png) ## User Details Page ![User details page](/images/effect-atom/user-detail-page.png) ## Add User Form ![Add user form](/images/effect-atom/add-user-page.png) ## Delete User Confirmation Dialog ![Add user form](/images/effect-atom/delete-user-dialog.png) ## How the Backend Works The application uses `json-server` as its backend. In the root of the project you cloned, you'll find a `db.json` file. `json-server` takes this file and automatically generates a full REST API from it. Each top-level key in the file becomes an endpoint. For example, our `db.json` has a `users` key, so `json-server` creates a `/users` endpoint that supports `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` requests. Any changes made through the API are persisted back to the file. `json-server` is a prototyping tool, not a production backend. But from the frontend's perspective, it behaves like a real API. It accepts HTTP requests and returns JSON responses. As you work through the course, you'll encounter 3 query parameters — `q`, `_page`, and `_limit` — in the API calls. These are not names I chose arbitrarily; they are reserved parameter names defined by `json-server`. - `q` performs a full-text search across all fields. For example, `GET /users?q=sophia` returns all users where any field contains `"sophia"`. - `_page` selects which page of results to return. - `_limit` controls how many items are returned per request. You don't need to understand `json-server` in depth to follow this course. Just know that when you see these parameters, they're part of `json-server`'s API, and I'll point them out when they first appear in the code. --- As discussed in the previous chapter, `json-server` persists all data in `db.json`. When you add a user, they're written to this file. When you delete a user, they're removed from it. During testing, you might delete several users or all of them. If you ever need to restore the original data, copy and paste the following into the `db.json` file in your project root: ```json title="db.json" { "users": [ { "id": "1", "firstName": "Emily", "lastName": "Johnson", "email": "emily.johnson@example.com", "company": { "name": "Dooley, Kozey and Cronin", "title": "Sales Manager" }, "address": { "address": "626 Main Street", "city": "Phoenix", "state": "Mississippi" } }, { "id": "2", "firstName": "Michael", "lastName": "Williams", "email": "michael.williams@example.com", "company": { "name": "Spinka - Dickinson", "title": "Support Specialist" }, "address": { "address": "385 Fifth Street", "city": "Houston", "state": "Alabama" } }, { "id": "3", "firstName": "Sophia", "lastName": "Brown", "email": "sophia.brown@example.com", "company": { "name": "Schiller - Zieme", "title": "Accountant" }, "address": { "address": "1642 Ninth Street", "city": "Washington", "state": "Alabama" } }, { "id": "4", "firstName": "James", "lastName": "Davis", "email": "james.davis@example.com", "company": { "name": "Pagac and Sons", "title": "Research Analyst" }, "address": { "address": "238 Jefferson Street", "city": "Seattle", "state": "Pennsylvania" } }, { "id": "5", "firstName": "Emma", "lastName": "Miller", "email": "emma.miller@example.com", "company": { "name": "Graham - Gulgowski", "title": "Quality Assurance Engineer" }, "address": { "address": "607 Fourth Street", "city": "Jacksonville", "state": "Colorado" } }, { "id": "6", "firstName": "Olivia", "lastName": "Wilson", "email": "olivia.wilson@example.com", "company": { "name": "Pfannerstill Inc", "title": "Research Analyst" }, "address": { "address": "547 First Street", "city": "Fort Worth", "state": "Tennessee" } }, { "id": "7", "firstName": "Alexander", "lastName": "Jones", "email": "alexander.jones@example.com", "company": { "name": "Dickens - Beahan", "title": "Web Developer" }, "address": { "address": "664 Maple Street", "city": "Indianapolis", "state": "Delaware" } }, { "id": "8", "firstName": "Ava", "lastName": "Taylor", "email": "ava.taylor@example.com", "company": { "name": "Nikolaus Inc", "title": "Chief Executive Officer" }, "address": { "address": "1197 First Street", "city": "Fort Worth", "state": "Rhode Island" } }, { "id": "9", "firstName": "Ethan", "lastName": "Martinez", "email": "ethan.martinez@example.com", "company": { "name": "Gorczany - Gottlieb", "title": "Legal Counsel" }, "address": { "address": "466 Pine Street", "city": "San Antonio", "state": "Louisiana" } }, { "id": "10", "firstName": "Isabella", "lastName": "Anderson", "email": "isabella.anderson@example.com", "company": { "name": "Pollich - Hilpert", "title": "Chief Financial Officer" }, "address": { "address": "1964 Oak Street", "city": "New York", "state": "Utah" } }, { "id": "11", "firstName": "Liam", "lastName": "Garcia", "email": "liam.garcia@example.com", "company": { "name": "Considine - Torp", "title": "Web Developer" }, "address": { "address": "576 Fifth Street", "city": "Denver", "state": "South Dakota" } }, { "id": "12", "firstName": "Mia", "lastName": "Rodriguez", "email": "mia.rodriguez@example.com", "company": { "name": "Miller, Schowalter and Wisozk", "title": "Business Analyst" }, "address": { "address": "1627 Sixth Street", "city": "Jacksonville", "state": "West Virginia" } } ] } ``` --- The term "state" means data that changes over time. In React applications, we typically work with two main types of state: **client state** and **server state**. ## Client State Client state refers to the state that is **owned and managed entirely within your application**. It exists only on the client side. For example, UI states (modal open/closed, form input values) and user preferences (theme selection, language settings) fall into this category. Here are two characteristics that define client state: - **Synchronous:** You can access client state using synchronous APIs. The data is immediately available and does not require network requests. - **Temporary:** Client state may get lost upon page reload (unless explicitly persisted) and is generally non-persistent between sessions. React provides several built-in mechanisms for managing client state. The most fundamental is the `useState` hook, which allows components to maintain local state. For more complex scenarios, React offers `useReducer` for state logic and `Context API` for sharing state across components without prop drilling. While React's built-in tools handle basic client state needs, larger applications often benefit from dedicated state management libraries. Among client-state management libraries, Zustand remains a popular choice. Other options include Redux Toolkit and Jotai, each offering different approaches to client state management. ## Server State Server state refers to the state that **originates from and is owned by an external system** (an API or a database). User accounts and profiles, business data (orders, transactions, inventory, customer records) and content management (articles, media files, user-generated content) are examples of server state. Here are two characteristics that define server state: - **Asynchronous:** The data is not immediately available as it must be fetched over the network. - **Persistent:** Server state lives on the remote server. As a result, it survives page reloads and browser sessions. When the page loads again, the browser simply refetches the existing data. ## Challenges of Server State Managing server state is more complex than client state. It introduces a set of challenges that client state simply doesn't have. ### Network reliability and error handling Server state introduces unpredictable failure scenarios. Network connections can fail, servers can return errors, and timeouts can occur at any moment. Managing these scenarios gracefully while maintaining a smooth user experience requires sophisticated error handling strategies. ### Loading states and user experience While waiting for remote data, applications must handle loading states effectively. This involves showing appropriate loading indicators, implementing fallback UIs when components aren't available, and managing the transition between loading, success, and error states. ### Data consistency and synchronization When server state is cached locally, your application essentially maintains two sources of truth: the remote server and the local cache. These can diverge in several ways. Other users might modify the same data you're viewing. Another tab in your browser could make updates that your current tab doesn't know about. Or your own pending requests might arrive at the server out of order, causing race conditions. Keeping these sources synchronized requires answering difficult questions: How do you detect when remote data has changed? How do you handle conflicts when local and server state disagree? How do you ensure users always see accurate information without constantly refetching everything? ### Cache invalidation and staleness Determining when cached data becomes stale and needs refreshing introduces significant complexity. You need mechanisms to receive updates when remote data changes, perform strategic refetches, and handle cache invalidation across different parts of your application. ### Optimistic updates and rollback scenarios Modern applications often implement optimistic updates to improve perceived performance. However, this introduces additional complexity. When a user makes a change, you can update the UI optimistically assuming the server call will succeed. But if it doesn't, you'll need a way to roll back those changes in your frontend state. Managing these rollback scenarios requires careful state tracking and recovery mechanisms. The challenges we discussed above are the reason why it’s recommended to use purpose-built libraries such as TanStack Query and SWR to manage server state. They abstract away much of this complexity, providing battle-tested solutions for caching, synchronization, and error handling that would be extremely difficult to implement correctly from scratch. --- Effect Atom is **a state management library for Effect**. It has adapters for React, Vue and SolidJS. As we discussed in the previous chapter, client state and server state have distinct characteristics and therefore have different requirements. This is why many state management libraries focus on either client state or server state. The split isn't perfectly strict—some libraries can handle both—but it's a useful mental model. So, which state does Effect Atom focus on? The answer is: both. That being said, roughly 90% of the state we deal with in typical React applications is server state. This is why server state is the core focus of this course. --- The Registry is the central coordinator that manages all Atoms in an application. An Atom is a reactive unit of state. It holds a value and notifies the Registry when that value changes. You can think of the registry as a container that: - Stores the current value of every active Atom - Knows which Atoms depend on which other Atoms - Notifies the right components when values change - Cleans up Atoms when they're no longer needed Let's look at each of these responsibilities. ## Centralizes Storage The Registry maintains a map that stores a Node for each active Atom: ```ts readonly nodes = new Map | string, Node>() ``` Each Node wraps an Atom and holds: - The current computed value - The list of parent Atoms (dependencies) - The list of child Atoms (dependents) - Subscribers (React components listening for changes) - Lifecycle state (is it initialized? is it stale?) When you read an Atom's value, the Registry either returns the cached value or computes it fresh. ## Tracks Dependencies Some Atoms read values from other Atoms. When this happens, the Registry automatically discovers these relationships. When an Atom computes its value, the Registry watches which other Atoms it accesses. If Atom A reads the value of Atom B during computation, the Registry records that A depends on B. This creates a dependency graph that the Registry uses to propagate changes. When B's value changes, the Registry recomputes A automatically. The tracking happens automatically. You don't need to manually declare dependencies. The Registry figures them out by observing what your Atoms actually read. ## Orchestrates Updates When an Atom's value changes, the Registry must update all dependent Atoms and notify all subscribers. This happens through a process called invalidation. First, the Registry marks all dependent Atoms as stale. Then, it walks through the dependency graph and recomputes each affected Atom. Finally, it notifies subscribers (your React components) so they can re-render with the new values. This process is surgical. The Registry knows exactly which Atoms depend on the changed value, so it only updates what's necessary. Components that don't use the changed Atom remain untouched. ## Manages Lifecycle Atoms don't live forever. The Registry manages when they're created and when they're cleaned up. **Creation** happens lazily. The Registry only creates a Node when something actually needs that Atom's value—either a component subscribes to it or another Atom reads from it. **Cleanup** happens when an Atom is no longer needed. An Atom can be removed when: - It has no subscribers (no React components watching it) - It has no children (no other Atoms depending on it) - It's not marked as `keepAlive` This automatic garbage collection prevents memory leaks. Atoms that are no longer in use get cleaned up without any manual intervention. To use Effect Atom in a Next.js app, we first need to create a Registry and make it available to the entire app. This way, components—no matter how deeply nested in the component tree—can read from and write to the same shared Registry. --- In `providers/atom-registry-provider.tsx`, add the following code: ```tsx title="providers/atom-registry-provider.tsx" "use client"; import { ReactNode } from "react"; import { RegistryProvider } from "@effect/atom-react"; export function AtomRegistryProvider({ children }: { children: ReactNode }) { return {children}; } ``` We import `RegistryProvider` and wrap the `children` prop with it. When `RegistryProvider` renders, it creates a Registry instance and makes it available to the entire component tree through React Context. We also explicitly mark this file with `"use client"` because the Registry relies on React Context and hooks to manage state updates, which are client-side features. --- Next, import `AtomRegistryProvider` into `app/layout.tsx` and wrap your entire application with it: ```tsx collapse={11-27} ins={8, 39, 43} title="app/layout.tsx" import type { Metadata } from "next"; import { Geist, Geist_Mono, Inter } from "next/font/google"; import "./globals.css"; import { Toaster } from "@/components/ui/sonner"; import { AtomRegistryProvider } from "@/providers/atom-registry-provider"; import { ProgressBarProvider } from "@/providers/progress-bar-provider"; const inter = Inter({ subsets: ["latin"], variable: "--font-sans" }); const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "Effect Atom Demo", description: "A Next.js application demonstrating reactive state management using Effect Atom.", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return (

{children}

); } ``` --- import { Note } from "@/components/note"; In `services/user-service.ts`, add the following code: ```tsx title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UsersSchema, type UsersResponse } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers(): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } return { getUsers }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` We define `UserService` using `ServiceMap.Service`. Let's break down the key parts. We obtain an `HttpClient` instance and pipe it through `filterStatusOk`. This ensures that any non-2xx response automatically fails the Effect with a [HttpClientError](https://www.effective.software/courses/effect-http-client/error-types-overview#httpclienterror) with reason set to a `StatusCodeError`, so we don't have to manually check status codes to distinguish between successful and failed responses. [By default, `HttpClient` does not treat non-2xx status codes as errors](https://www.effective.software/courses/effect-http-client/filtering-responses/default-behavior). The `getUsers` function constructs a `GET` request with the `_limit` query parameter and executes it. It returns an object with two properties: `users` and `usersCount`. The `users` property contains the response body, parsed and validated against `UsersSchema`. If the response doesn't match the schema, the Effect fails with a [SchemaError](https://www.effective.software/courses/effect-http-client/error-types-overview#schemaerror). The `usersCount` property contains the total number of users, read from the `x-total-count` response header. Notice the `Effect.delay("1 second")` line. Since our API reads from a local `db.json` file, responses are nearly instant. The 1-second delay simulates realistic network latency, giving us a chance to observe loading states. The `_limit` query parameter and the `x-total-count` response header are specific to json-server. The `_limit` parameter controls how many items are returned per request. The `x-total-count` header contains the total number of users, which we'll use to implement pagination later. The `UserService` depends on `HttpClient`, which we provide via `FetchHttpClient.layer` in the static `layer` property. --- **An Atom Runtime is a bridge between Effect's service system and Effect Atom's reactive system.** It takes a Layer (which contains your services) and creates a specialized runtime that knows how to: - Provide those services to any Atom that needs them - Execute Effects within the context of those services - Handle the async lifecycle (loading, success, failure) automatically Think of it this way: a regular Effect Runtime knows how to run Effects. An Atom Runtime knows how to run Effects and turn them into reactive Atoms that work with the Registry. In `atom-runtime.ts`, add the following code: ```ts title="atom-runtime.ts" import { Atom } from "effect/unstable/reactivity"; import { UserService } from "@/services/user-service"; export const atomRuntime = Atom.runtime(UserService.layer); ``` We pass `UserService.layer` to `Atom.runtime`. This creates an Atom Runtime that has access to `UserService`. Any Atom created through this runtime can now call methods on `UserService` — like `getUsers()` and others we'll add later — without manually providing the service.. The Atom Runtime exposes several methods for creating Atoms: - `.atom()`: Creates an Atom from an Effect - `.fn()`: Creates a callable Atom (useful for mutations) - `.pull()`: Creates an Atom that pulls from a Stream We'll use the `.atom()` method to create our first Atom in the next chapter. --- Now that we have an Atom Runtime with access to `UserService`, we can create an Atom that fetches users' data. In `atoms/user.ts`, add the following code: ```ts title="atoms/user.ts" import { Effect } from "effect"; import { atomRuntime } from "@/atom-runtime"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime.atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ); ``` We call `atomRuntime.atom()` and pass it an Effect. Inside the Effect, we yield the `UserService` to get the service instance, then call `getUsers()` on it to fetch users' data. Because `usersAtom` runs an Effect, it's called an **effectful Atom** — a term we'll use throughout the course to refer to any Atom that runs an Effect. --- import { Note } from "@/components/note"; We've created the `usersAtom`. Now, let's read its value in the `UserGrid` component. To read an atom's value, we use the **`useAtomValue`** hook. Replace the code inside `components/user-grid.tsx` with the following: ```tsx title="components/user-grid.tsx" {8} "use client"; import { useAtomValue } from "@effect/atom-react"; import { usersAtom } from "@/atoms/user"; export function UserGrid() { const usersResult = useAtomValue(usersAtom); console.log("Users Result: ", usersResult); return (

      {JSON.stringify(usersResult, null, 2)}

); } ``` The value returned by `useAtomValue(usersAtom)` is an `AsyncResult` type, which can be in one of the following three states: - `Initial`: Data fetching hasn't completed yet - `Success`: Data fetching succeeded with a value - `Failure`: Data fetching failed with an error Let's observe these states in action. Make sure your app is running, then visit `localhost:3001`. Open the browser console. You'll see `usersResult` logged multiple times. Some in the `Initial` state (`_tag: "Initial"`) and some in the `Success` state (`_tag: "Success"`). The `Success` state is also visible on the page as JSON. To see the `Failure` state, go to `user-service.ts` and change the endpoint from `/users` to `/usersx` (which doesn't exist). Visit the home page again. You'll see the `Failure` state (`_tag: "Failure"`) on both the page and in the browser console. Remember to revert the endpoint back to `/users` before continuing. --- import { Note } from "@/components/note"; Currently, we're rendering the raw structure of the `AsyncResult` object to visualize its internal state. Now that we understand the three states an `AsyncResult` can be in, let's replace the JSON dump with a proper UI. What does a proper UI for async state look like? We need to account for three states: - **Initial:** Data fetching is in progress. We show a spinner. - **Failure:** Data fetching failed. We show the error name and message. - **Success:** Data fetching succeeded. We render the users. Replace the existing code inside `components/user-grid.tsx` with the following: ```tsx title="components/user-grid.tsx" {5, 21} "use client"; import { useAtomValue } from "@effect/atom-react"; import { Cause } from "effect"; import { AsyncResult, Atom } from "effect/unstable/reactivity"; import { FailureCard } from "@/components/failure-card"; import { UserEmptyCard } from "@/components/user-empty-card"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { UserSuccessCard } from "@/components/user-success-card"; import { getErrorInfo } from "@/lib/utils"; import { usersAtom } from "@/atoms/user"; const selectUsers = (result: Atom.Type) => AsyncResult.map(result, (data) => data.users); export function UserGrid() { const usersResult = useAtomValue(usersAtom, selectUsers); return AsyncResult.match(usersResult, { onInitial: () => , onFailure: (failure) => { const error = Cause.squash(failure.cause); const { title, message } = getErrorInfo(error); return ; }, onSuccess: (success) => { const users = success.value; if (users.length === 0) { return ; } return (

{users.map((user) => ( ))}

); }, }); } ``` If you see a React hooks order error after saving, do a full page refresh. This happens because the previous version of `UserGrid` used `useAtomValue` without a transform function, and the new version uses one. The different code paths call different hooks, which triggers a React warning during hot reload. Let's understand what's going on here. The `UserGrid` component needs the `users` array. But `usersAtom` contains both the `users` array and the users count. So, we pass a transform function named `selectUsers` as the second argument to `useAtomValue`. `selectUsers` takes in the full `AsyncResult` and uses `AsyncResult.map` to extract just the `users` array. This way, `usersResult` contains only the `users`. `AsyncResult.match` takes an `AsyncResult` and an object with three handlers, one for each state: - `onInitial` renders a spinner while data is being fetched. - `onSuccess` receives the success value (the `users` array) and renders the user cards, or an empty state if the array is empty. - `onFailure` deserves a closer look. The failure result contains a `cause` property, but this isn't the error directly. It's an Effect `Cause`, which is a wrapper that can represent complex error scenarios like multiple failures or interruptions. `Cause.squash` extracts the underlying error from this wrapper. Once we have the error, we pass it to `getErrorInfo`, which reads the error's name and message to produce a user-friendly title and description for the `FailureCard`. `AsyncResult.match` guarantees exhaustiveness. TypeScript will error if you forget to handle any of the three states. Try commenting out one of the handlers to see this in action. Now, visit the home page. You should see 12 user cards rendered. To see the `FailureCard` in action, go to `user-service.ts` and change the endpoint from `/users` to `/usersx` (which doesn't exist). Visit the home page again. You should see the failure card rendered with the error title and message. Remember to revert the endpoint back to `/users` before continuing. --- import { Note } from "@/components/note"; Effect Atom provides another API for handling async states: `AsyncResult.builder`. Replace the existing code inside `components/user-grid.tsx` with the following: ```tsx title="components/user-grid.tsx" {19} "use client"; import { useAtomValue } from "@effect/atom-react"; import { AsyncResult, Atom } from "effect/unstable/reactivity"; import { FailureCard } from "@/components/failure-card"; import { UserEmptyCard } from "@/components/user-empty-card"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { UserSuccessCard } from "@/components/user-success-card"; import { usersAtom } from "@/atoms/user"; const selectUsers = (result: Atom.Type) => AsyncResult.map(result, (data) => data.users); export function UserGrid() { const usersResult = useAtomValue(usersAtom, selectUsers); return AsyncResult.builder(usersResult) .onInitial(() => ) .onErrorTag("ClientError", (error) => ( )) .onErrorTag("ServerError", (error) => ( )) .onErrorTag("ParseError", (error) => ( )) .onDefect(() => ( )) .onSuccess((users) => users.length === 0 ? ( ) : (

{users.map((user) => ( ))}

), ) .render(); } ``` `AsyncResult.builder` provides two advantages over `AsyncResult.match`: ### Fine-grained error handling Instead of handling all errors in a single `onFailure` callback, you can use `onErrorTag` to handle specific error types individually. This lets you show different UI for different errors. ### Access to the `waiting` state. Each handler receives metadata as its second parameter, including a `waiting` boolean, which indicates whether data is being refreshed in the background. We'll explore the `waiting` boolean in detail in the [Showing Stale Data During Refresh](https://www.effective.software/courses/effect-atom/showing-stale-data-during-refresh) chapter. Unlike `AsyncResult.match`, `AsyncResult.builder` doesn't guarantee exhaustiveness. TypeScript won't error if you forget to handle an error type. --- import { Note } from "@/components/note"; When an effectful Atom runs its Effect, the Registry caches the returned value. Any component that reads the Atom afterward gets the cached value instantly, without re-running the Effect. However, this cache only lives as long as at least one component subscribed to the Atom remains mounted. When every component that reads the Atom unmounts, the Registry discards the cache (after a short grace period of 400ms). A component is **subscribed to an Atom** when it uses a hook such as `useAtomValue` to read the Atom's value. The subscription starts when the component mounts and ends when it unmounts. When a component **mounts**, React inserts its elements into the DOM for the first time. When it **unmounts**, React removes those elements from the DOM permanently. To see this in action, go to the home page. Then click the `Add User` link to navigate away. Now return to the home page. Notice the spinner appears again. What happened? When you navigated away, the `UserGrid` component unmounted. Since no other components were subscribed to `usersAtom`, the Registry discarded its cache. When you navigated back, `UserGrid` mounted again, but the cache was empty, so the Atom had to run its Effect again. This default behavior makes sense for many scenarios. But in our case, the users' data doesn't change frequently. Why fetch the same data and show a spinner every time the home page loads? Instead, we can persist the cache using `Atom.keepAlive`. Update the `usersAtom` as shown below: ```ts ins={2, 15} title="atoms/user.ts" import { Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.keepAlive); ``` Now navigate away from the home page and return. The spinner no longer appears. The data is served instantly from cache. --- **When we use `Atom.keepAlive`, the cache persists forever.** The Atom never refetches _automatically_. This works well for data that rarely changes, but it also means users could be looking at stale data indefinitely. What if you want the benefits of caching—no spinner on every page visit—but also want the data to eventually refresh? This is where `Atom.setIdleTTL` comes in. Instead of keeping the cache alive forever, you specify how long the cache should persist after all subscribers unmount. Once that time passes, the Registry discards the cache. The next time a subscriber mounts, the Atom fetches fresh data. Let's set a 2-second TTL to see this in action. Update the `usersAtom` as shown below: ```ts title="atoms/user.ts" {1, 15} import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.seconds(2))); ``` Now, go to the home page and wait for the users to load. Click the **Add User** link to navigate away. Wait about 3 seconds, then return to the home page. You'll see the spinner because the cache expired while you were away. Now try again, but return within 2 seconds. The data loads instantly from cache because the TTL hadn't expired yet. Before continuing, update the TTL to a more practical value: ```ts .pipe(Atom.setIdleTTL(Duration.hours(1))); ``` --- import { Note } from "@/components/note"; So far, the `UserGrid` component handles loading states by checking the result's state. When data is loading, it renders a spinner. When data is ready, it renders the users. This approach works, but it means every component that consumes Atom data needs to handle loading states explicitly. React provides a cleaner pattern for this: **Suspense**. Effect Atom integrates with React Suspense through the `useAtomSuspense` hook. Instead of returning the loading state to your component, `useAtomSuspense` suspends the component until the data is ready. You then wrap your component in a `` boundary and provide a fallback UI. When a component "suspends," it tells React: "I'm not ready to render yet." React stops rendering that component and looks up the component tree for the nearest `` boundary. It then renders that boundary's `fallback` prop until the component is ready. Once the data arrives, React renders the component with the data. The component never sees the loading state. It either renders with data or doesn't render at all. ## Creating a Suspense-Enabled UserGrid Component Create a new file `components/user-grid-suspense.tsx`: ```tsx title="components/user-grid-suspense.tsx" {3, 10} "use client"; import { useAtomSuspense } from "@effect/atom-react"; import { UserSuccessCard } from "@/components/user-success-card"; import { usersAtom } from "@/atoms/user"; export function UserGridSuspense() { const result = useAtomSuspense(usersAtom); return (

{result.value.users.map((user) => ( ))}

); } ``` Notice how much simpler this component is. There's no need to check for loading states. `useAtomSuspense` suspends the component until the data is available. When the component renders, we know we have data: `result` is always a `Success`, and `result.value` contains the data returned by `usersAtom`, from which we access the `users` array. ## Adding the Suspense Boundary Now, inside `app/page.tsx`, let's render `UserGridSuspense` instead of `UserGrid`: ```tsx ins={3, 7-8, 26-28} del={6, 25} title="app/page.tsx" "use client"; import { Suspense } from "react"; import { Link } from "react-transition-progress/next"; import { UserGrid } from "@/components/user-grid"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { UserGridSuspense } from "@/components/user-grid-suspense"; import { UserPagination } from "@/components/user-pagination"; import { UserSearchBar } from "@/components/user-search-bar"; export default function HomePage() { return (

Users

+ Add User

); } ``` The `` boundary catches the suspension from `useAtomSuspense` and renders`` while the data loads. Once the data is ready, React renders `UserGridSuspense` with the users. The home page behaves exactly as before. The spinner shows while data loads, then the user cards appear. The difference is structural: the loading logic now lives in the Suspense boundary rather than inside the `UserGridSuspense` component. --- import { Note } from "@/components/note"; In the previous chapter, we created a Suspense-enabled `UserGrid` component. However, we didn't handle errors. If the data fetch fails, `useAtomSuspense` throws the error and the app crashes. To catch these errors and prevent crashes, React provides Error Boundaries. They wrap a section of your component tree and display a fallback UI when any child component throws. ## Using React Error Boundary First, install the `react-error-boundary` package: ```bash pnpm add react-error-boundary ``` Create a new file `components/error-fallback.tsx`: ```tsx title="components/error-fallback.tsx" "use client"; import type { FallbackProps } from "react-error-boundary"; import { FailureCard } from "@/components/failure-card"; import { getErrorInfo } from "@/lib/utils"; export function ErrorFallback({ error, resetErrorBoundary }: FallbackProps) { const { title, message } = getErrorInfo(error); return ( ); } ``` Now update `app/page.tsx` to wrap the Suspense boundary with an Error Boundary: ```tsx ins={4, 5, 8, 14, 17, 31, 35} title="app/page.tsx" "use client"; import { Suspense } from "react"; import { useAtomRefresh } from "@effect/atom-react"; import { ErrorBoundary } from "react-error-boundary"; import { Link } from "react-transition-progress/next"; import { ErrorFallback } from "@/components/error-fallback"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { UserGridSuspense } from "@/components/user-grid-suspense"; import { UserPagination } from "@/components/user-pagination"; import { UserSearchBar } from "@/components/user-search-bar"; import { usersAtom } from "@/atoms/user"; export default function HomePage() { const refreshUsers = useAtomRefresh(usersAtom); return (

Users

+ Add User

); } ``` The Error Boundary wraps the Suspense boundary. If the data fetch fails, the Error Boundary catches the error and renders `ErrorFallback` instead of crashing the app. Notice that we use the `useAtomRefresh` hook. This hook takes an Atom and returns a function that, when called, tells the Registry to invalidate the Atom and re-run its Effect. We store this function in `refreshUsers`. We then pass `refreshUsers` as the `onReset` prop of the `ErrorBoundary`. When the user clicks the retry button in `ErrorFallback`, it calls `resetErrorBoundary`, which does two things. First, it resets the Error Boundary's internal state so it attempts to render its children again. Second, it triggers the `onReset` callback, which calls `refreshUsers` to re-run the `usersAtom`'s Effect. Without `onReset`, the Error Boundary would try to re-render the children, but the Atom's failed result would still be cached. It would throw the same error again immediately. To see the Error Boundary in action, go to `services/user-service.ts` and change the endpoint from `/users` to `/usersx` (an endpoint that doesn't exist). Visit the home page. You'll see the `ErrorFallback` component rendered with the error title and message. Click the **Try again** button. Since the endpoint is still invalid, you'll see the error again. ## Handling Errors Manually If you prefer to handle errors within the component rather than using an Error Boundary, `useAtomSuspense` accepts an `includeFailure` option. First, remove the `ErrorBoundary` wrapper and the related imports from `app/page.tsx`: ```tsx del={4, 5, 8, 14, 17, 31, 35} title="app/page.tsx" "use client"; import { Suspense } from "react"; import { useAtomRefresh } from "@effect/atom-react"; import { ErrorBoundary } from "react-error-boundary"; import { Link } from "react-transition-progress/next"; import { ErrorFallback } from "@/components/error-fallback"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { UserGridSuspense } from "@/components/user-grid-suspense"; import { UserPagination } from "@/components/user-pagination"; import { UserSearchBar } from "@/components/user-search-bar"; import { usersAtom } from "@/atoms/user"; export default function HomePage() { const refreshUsers = useAtomRefresh(usersAtom); return (

Users

+ Add User

); } ``` Now update the code inside `components/user-grid-suspense.tsx`: ```tsx ins={3-4, 6, 9, 13-14, 16-21} title="components/user-grid-suspense.tsx" "use client"; import { useAtomRefresh, useAtomSuspense } from "@effect/atom-react"; import { Cause } from "effect"; import { FailureCard } from "@/components/failure-card"; import { UserSuccessCard } from "@/components/user-success-card"; import { getErrorInfo } from "@/lib/utils"; import { usersAtom } from "@/atoms/user"; export function UserGridSuspense() { const result = useAtomSuspense(usersAtom, { includeFailure: true }); const refresh = useAtomRefresh(usersAtom); if (result._tag === "Failure") { const error = Cause.squash(result.cause); const { title, message } = getErrorInfo(error); return ; } return (

{result.value.users.map((user) => ( ))}

); } ``` With `includeFailure: true`, the `useAtomSuspense` hook returns the `Failure` result instead of throwing. This gives you full control over how errors are displayed. `Cause.squash` extracts the underlying error from the `Cause`. This is necessary because Effect wraps errors in a `Cause` type that can represent complex error scenarios like multiple failures or interruptions. For the retry button, we use `useAtomRefresh`, the same hook we used in the Error Boundary approach. We refresh `usersAtom` because it's the Atom that runs the Effect to fetch users' data. If you still have the endpoint set to `/usersx`, visit the home page. You'll see the `FailureCard` component rendered with the error details and a **Try again** button, handled entirely within the component rather than by an Error Boundary. Before continuing, make sure to revert the users endpoint back to `/users` in `services/user-service.ts`. --- Currently, if you click the `View Details` link on any user card, you get redirected to the user's detail page. But on that page, you just see the text **User Detail**. We need to fetch the specific user's data and render their details. ## Adding the `getUser` Method First, add the `getUser` function to your `UserService` in `services/user-service.ts`: ```ts collapse={30-60} ins={14, 16, 62-79, 81 } title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UserSchema, UsersSchema, type User, type UsersResponse, } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers(): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Get User ============ function getUser(id: string): Effect.Effect { return client.get(`${apiBaseUrl}/users/${id}`).pipe( Effect.delay("1 second"), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } return { getUsers, getUser }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` This follows the same pattern as `getUsers`, but fetches a single user by ID instead of a list. ## Why We Need Atom.family With `usersAtom`, we fetch the same data (the list of all users) every time. There's only one version of this data, so a single Atom works perfectly. But a user detail page is different. Each user has a unique ID, and we need to fetch different data depending on which user we're viewing. User 1's data is different from User 3's data. We can't use a single Atom because the data depends on which user ID we pass in. This is exactly what `Atom.family` solves. It creates a factory function that produces a separate Atom for each unique parameter: - **userAtom("1"):** creates an Atom that fetches user 1's data - **userAtom("1"):** returns the **same** Atom (already created) - **userAtom("3"):** creates a **different** Atom for user 3 **Think of `Atom.family` as a cache of Atoms keyed by their parameters.** Each user's data is fetched and cached independently. If you view user 1, navigate away, then come back, the data loads instantly from cache (assuming the TTL hasn't expired). Meanwhile, user 3's data remains unaffected. ## Creating the User Atom Now create the user Atom in `atoms/user.ts`: ```ts ins={17-27} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); ``` We pass `Atom.family` a function that receives an `id` and returns an Atom. Each unique `id` gets its own Atom instance with its own cache and TTL. ## Displaying User Details Now replace the code inside `components/user-detail.tsx` with the following: ```tsx title="components/user-detail.tsx" "use client"; import { useParams } from "next/navigation"; import { useAtomValue } from "@effect/atom-react"; import { AsyncResult } from "effect/unstable/reactivity"; import { userAtom } from "@/atoms/user"; import { FailureCard } from "@/components/failure-card"; import { UserDetailsCard } from "@/components/user-details-card"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { getErrorInfo } from "@/lib/utils"; export function UserDetail() { const params = useParams<{ id: string }>(); const result = useAtomValue(userAtom(params.id)); return AsyncResult.builder(result) .onInitial(() => ) .onError((error) => { const { title, message } = getErrorInfo(error); return ; }) .onDefect((defect) => { const { title, message } = getErrorInfo(defect); return ; }) .onSuccess((user) => ) .render(); } ``` We extract the `id` from the URL parameters using Next.js's `useParams` hook, then pass it to `userAtom(params.id)`. This gives us the Atom instance for that specific user. The rest follows the same pattern we used in `UserGrid`. We handle loading, error, and success states using `AsyncResult.builder`. Click the `View Details` link on any user card. You'll be redirected to the user details page where you'll see the user's information. If you navigate back and revisit the same user, you won't see the loading spinner because the data is already cached. --- So far, we've only read data. But real applications also need to mutate data: create, update, and delete. Let's learn how to handle deletion using Effect Atom. ## Deleting a User Each user card has a trash icon in the top-right corner. Click it, and a confirmation dialog appears. Click **Delete**—nothing happens. That's because the `handleDelete` function inside `components/user-delete-dialog.tsx` is empty. Let's fix that. ## Adding the deleteUser Method First, add the `deleteUser` method to your `UserService` in `services/user-service.ts`: ```ts collapse={30-79} ins={81-90, 92} title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UserSchema, UsersSchema, type User, type UsersResponse, } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers(): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Get User ============ function getUser(id: string): Effect.Effect { return client.get(`${apiBaseUrl}/users/${id}`).pipe( Effect.delay("1 second"), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Delete User ============ function deleteUser(userId: string): Effect.Effect { return client.del(`${apiBaseUrl}/users/${userId}`).pipe( Effect.delay("1 second"), Effect.asVoid, Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), ); } return { getUsers, getUser, deleteUser }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` ## Adding the Delete User Atom Now add the delete user Atom in `atoms/user.ts`: ```ts ins={29-35} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), ); ``` Instead of `atomRuntime.atom()`, which we've used so far, we're using `atomRuntime.fn()` here. Let's understand what this method does and why mutations need it. ## Understanding atomRuntime.fn() So far, we've used `atomRuntime.atom()` to create Atoms. An Atom created with `.atom()` runs its Effect automatically when a component subscribes to it. For example, the moment `UserGridSuspense` mounts and calls `useAtomSuspense(usersAtom)`, the Effect executes and fetches the data. You don't trigger it manually. The Atom also caches the result, tracks dependencies, and recomputes when those dependencies change. Mutations don't work this way. A delete operation shouldn't run automatically when a component mounts. It should run only when the user explicitly clicks the Delete button. This is what `atomRuntime.fn()` provides. It creates a function Atom that sits idle until you invoke it with an argument. Nothing executes until you call it. There's another difference worth noting. An Atom created with `.atom()` holds persistent state. It always has a current value (the list of users, a single user's data) that components can read at any time. A function Atom created with `.fn()` represents a one-off command. It tracks the result of the latest invocation, not an ongoing piece of state. Once the delete completes, the result tells you whether it succeeded or failed, but there's no persistent value to cache and share across components. To use a function Atom in a component, we use `useAtomSet`: ```tsx const deleteUser = useAtomSet(deleteUserAtom, { mode: "promiseExit" }); const exit = await deleteUser(userId); ``` The `mode: "promiseExit"` option makes the function return a `Promise>`. An Exit is Effect's way of representing the outcome of an operation. Either success with a value, or failure with a cause. This gives you explicit control over error handling. ## Adding User Deletion Logic Now update `components/user-delete-dialog.tsx` as shown below: ```tsx ins={4-6, 21, 34, 44-62} collapse={66-101} title="components/user-delete-dialog.tsx" "use client"; import { useState } from "react"; import { useAtomSet } from "@effect/atom-react"; import { Cause, Exit, Option } from "effect"; import { toast } from "sonner"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/ui/dialog"; import { deleteUserAtom } from "@/atoms/user"; import type { User } from "@/schema/user-schema"; interface UserDeleteDialogProps { user: User; trigger: React.ReactNode; } export function UserDeleteDialog({ user, trigger }: UserDeleteDialogProps) { const [open, setOpen] = useState(false); const [isDeleting, setIsDeleting] = useState(false); const [error, setError] = useState(null); const deleteUser = useAtomSet(deleteUserAtom, { mode: "promiseExit" }); function handleOpenChange(isOpen: boolean) { setOpen(isOpen); if (!isOpen) { setError(null); } } async function handleDelete() { setIsDeleting(true); setError(null); const exit = await deleteUser(user.id); setIsDeleting(false); if (Exit.isSuccess(exit)) { setOpen(false); toast.success("User deleted successfully", { description: `${user.firstName} ${user.lastName} has been deleted.`, }); } else { const failureOption = Cause.findErrorOption(exit.cause); const errorMessage = Option.isSome(failureOption) ? failureOption.value.message : "An unexpected error occurred"; setError(errorMessage); } } return ( ); } ``` Let's break down what this code does: - **Get the mutation function:** `useAtomSet(deleteUserAtom, { mode: "promiseExit" })` returns a callable function that returns a `Promise>`. - **Set loading state:** Before starting the operation, we set `isDeleting` to `true` and clear any previous errors. - **Execute the mutation:** `await deleteUser(user.id)` runs the Effect and returns an `Exit`. - **Handle the result:** We use `Exit.isSuccess()` to check if the operation succeeded. On success, we close the dialog and show a toast. On failure, we extract the error message from the `Cause` and display it. ## Testing User Deletion Click the trash icon on any user card, then click **Delete** in the confirmation dialog. You should see a toast confirming the user was deleted. But wait, the user card is still visible. Refresh the page manually. Now the deleted user is gone. The deletion works, but requiring a manual refresh isn't acceptable. The user grid should update automatically. We'll address this in the upcoming [Refreshing Data After Mutation](https://www.effective.software/courses/effect-atom/refreshing-data-after-mutation/using-automatic-cache-invalidation) chapter. --- When you click the **Add User** link on the home page, you're taken to a page with an "Add New User" form. Fill it out and submit—nothing happens. That's because the `onSubmit` handler in `components/add-user-form.tsx` is empty. Let's wire it up. ## Adding the addUser Method In `services/user-service.ts`, add the `addUser` method: ```ts ins={16, 93-114, 116} collapse={31-91} title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UserSchema, UsersSchema, type AddUserFormValues, type User, type UsersResponse, } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers(): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Get User ============ function getUser(id: string): Effect.Effect { return client.get(`${apiBaseUrl}/users/${id}`).pipe( Effect.delay("1 second"), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Delete User ============ function deleteUser(userId: string): Effect.Effect { return client.del(`${apiBaseUrl}/users/${userId}`).pipe( Effect.delay("1 second"), Effect.asVoid, Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), ); } // ============ Add User ============ function addUser( user: AddUserFormValues, ): Effect.Effect { return HttpClientRequest.post(`${apiBaseUrl}/users`).pipe( HttpClientRequest.bodyJson(user), Effect.delay("1 second"), Effect.flatMap(client.execute), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } return { getUsers, getUser, deleteUser, addUser }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` ## Adding the Add User Atom In `atoms/user.ts`, add the the `addUserAtom`: ```ts ins={5, 38-44} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string, get) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); ``` This follows the same pattern as `deleteUserAtom`. Notice the syntax is slightly different. `atomRuntime.fn()()` explicitly specifies the input type as a generic parameter. With `deleteUserAtom`, TypeScript could infer the input type from the `userId: string` annotation. Here we pass the type explicitly so that user inside the function is correctly typed as `AddUserFormValues`. ## Updating the onSubmit Handler Update `components/add-user-form.tsx` as shown below: ```tsx ins={5, 7, 10, 22, 35, 53-72} collapse={76-221} title="components/add-user-form.tsx" "use client"; import { startTransition, useId, useState } from "react"; import { useRouter } from "next/navigation"; import { useAtomSet } from "@effect/atom-react"; import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"; import { Cause, Exit, Option } from "effect"; import { useForm } from "react-hook-form"; import { useProgress } from "react-transition-progress"; import { toast } from "sonner"; import { FormErrorMessage, FormFieldErrorMessage, } from "@/components/form-messages"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { Card, CardContent } from "@/components/ui/card"; import { Input } from "@/components/ui/input"; import { Label } from "@/components/ui/label"; import { addUserAtom } from "@/atoms/user"; import { AddUserFormStandardSchema, type AddUserFormValues, } from "@/schema/user-schema"; export function AddUserForm() { const id = useId(); const router = useRouter(); const startProgress = useProgress(); const [globalError, setGlobalError] = useState(null); const addUser = useAtomSet(addUserAtom, { mode: "promiseExit" }); const { register, handleSubmit, formState: { errors, isSubmitting }, } = useForm({ resolver: standardSchemaResolver(AddUserFormStandardSchema), defaultValues: { firstName: "", lastName: "", email: "", company: { name: "", title: "" }, address: { address: "", city: "", state: "" }, }, }); const onSubmit = async (data: AddUserFormValues) => { setGlobalError(null); const exit = await addUser(data); if (Exit.isSuccess(exit)) { const user = exit.value; toast.success("User Added Successfully", { description: `${user.firstName} ${user.lastName} was added successfully.`, }); startTransition(() => { startProgress(); router.push("/"); }); } else { const failureOption = Cause.findErrorOption(exit.cause); const errorMessage = Option.isSome(failureOption) ? failureOption.value.message : "An unexpected error occurred"; setGlobalError(errorMessage); } }; return (

{/* First Name */}

First Name

{/* Last Name */}

Last Name

{/* Email */}

{/* Company Name */}

Company Name

{/* Job Title */}

Job Title

{/* Address Info */}

Street Address

City

State

); } ``` This follows the same pattern as the delete handler: - **Clear previous errors:** Reset any error state before attempting the operation. - **Execute the mutation:** `await addUser(data)` submits the form data and returns an `Exit`. - **Handle success:** Extract the created user from `exit.value`, show a success toast, then redirect to the home page. - **Handle failure:** Extract the error message and display it on top of the form. ## Testing Add User Fill out the **Add User** form with valid data and submit. You should see a success toast, and you'll be redirected to the home page. But just like with deletion, the new user doesn't appear in the list. Refresh the page manually, and you'll see the newly added user. We have the same problem: the user grid's cache is stale, and it doesn't know that the data has changed. We'll fix this next. --- import { Note } from "@/components/note"; When we delete a user, the user list should update automatically. Users shouldn't need to manually refresh the page to see their changes. Effect Atom provides a reactivity system that handles exactly this. ## How Reactivity Works Effect Atom's reactivity is built on a simple concept: shared keys. - **Tag Atoms with keys:** You mark Atoms with reactivity keys that describe what data they represent. For example, the users Atom might have the key `"users"`. - **Tag mutations with keys:** You mark mutations with the same keys to indicate what data they affect. A delete user mutation would also use the key `"users"`. - **Automatic invalidation:** When a mutation tagged with `"users"` completes successfully, Effect Atom automatically invalidates (refreshes) all Atoms tagged with `"users"`. This creates a declarative system where you describe relationships once, and the framework handles synchronization. Automatic invalidation only works when the target Atom has active subscribers. If no component is currently subscribed to the Atom, the invalidation signal has no effect. We'll see why this matters shortly. ## Setting Up Reactivity Update `usersAtom` in `atoms/user.ts` to declare their reactivity keys: ```ts collapse={18-44} title="atoms/user.ts" {16} import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); ``` `Atom.withReactivity(["users"])` tags this Atom with the `"users"` key. Any mutation that invalidates `"users"` will cause this Atom to refresh. Now update `deleteUserAtom` to trigger invalidation: ```ts collapse={1-28, 39-45} ins={36} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); ``` The `{ reactivityKeys: ["users"] }` option tells the reactivity system: "When this operation succeeds, invalidate everything tagged with `'users'`." ## Testing Automatic Invalidation Let's verify that everything works. ### Testing User Deletion Click the trash icon on any user card and confirm. The toast appears, and the user card disappears from the grid. You no longer need to manually refresh the page. The `usersAtom` automatically refetched the data because the `deleteUserAtom` mutation invalidated the `"users"` key. This works because when you delete a user, you're on the home page. The `UserGridSuspense` component is mounted and subscribed to `usersAtom`. When the reactivity system invalidates the `"users"` key, there's an active subscriber listening, so the Atom refetches immediately. ## Why Reactivity Keys Don't Work for Adding Users You might wonder: why not add `reactivityKeys: ["users"]` to `addUserAtom` as well? The problem is that when you add a user, you're on the `/add-user` page. The `UserGridSuspense` component is not mounted, which means no component is subscribed to `usersAtom`. The reactivity system invalidates the `"users"` key, but since nothing is listening, the invalidation has no effect. When you navigate back to the home page, `usersAtom` still holds its old cached data. You won't see the newly added user. Reactivity keys are subscription-driven. They work when the target Atom has active subscribers. For mutations that happen on the same page as the data they affect (like delete), they work perfectly. For mutations that happen on a different page (like add), we need a different approach. ## Refreshing Before Navigation The solution is to explicitly refresh `usersAtom` after adding a user, before navigating back to the home page. Update `components/add-user-form.tsx` as shown below: ```ts collapse={77-222} ins={5, 22, 36, 60} title="components/add-user-form.tsx" "use client"; import { startTransition, useId, useState } from "react"; import { useRouter } from "next/navigation"; import { useAtomRefresh, useAtomSet } from "@effect/atom-react"; import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"; import { Cause, Exit, Option } from "effect"; import { useForm } from "react-hook-form"; import { useProgress } from "react-transition-progress"; import { toast } from "sonner"; import { FormErrorMessage, FormFieldErrorMessage, } from "@/components/form-messages"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { Card, CardContent } from "@/components/ui/card"; import { Input } from "@/components/ui/input"; import { Label } from "@/components/ui/label"; import { addUserAtom, usersAtom } from "@/atoms/user"; import { AddUserFormStandardSchema, type AddUserFormValues, } from "@/schema/user-schema"; export function AddUserForm() { const id = useId(); const router = useRouter(); const startProgress = useProgress(); const [globalError, setGlobalError] = useState(null); const addUser = useAtomSet(addUserAtom, { mode: "promiseExit" }); const refreshUsers = useAtomRefresh(usersAtom); const { register, handleSubmit, formState: { errors, isSubmitting }, } = useForm({ resolver: standardSchemaResolver(AddUserFormStandardSchema), defaultValues: { firstName: "", lastName: "", email: "", company: { name: "", title: "" }, address: { address: "", city: "", state: "" }, }, }); const onSubmit = async (data: AddUserFormValues) => { setGlobalError(null); const exit = await addUser(data); if (Exit.isSuccess(exit)) { const user = exit.value; refreshUsers(); toast.success("User Added Successfully", { description: `${user.firstName} ${user.lastName} was added successfully.`, }); startTransition(() => { startProgress(); router.push("/"); }); } else { const failureOption = Cause.findErrorOption(exit.cause); const errorMessage = Option.isSome(failureOption) ? failureOption.value.message : "An unexpected error occurred"; setGlobalError(errorMessage); } }; return (

{/* First Name */}

First Name

{/* Last Name */}

Last Name

{/* Email */}

{/* Company Name */}

Company Name

{/* Job Title */}

Job Title

{/* Address Info */}

Street Address

City

State

); } ``` `useAtomRefresh` takes an Atom and returns a function that, when called, tells the Registry to invalidate the Atom and re-run its Effect. We call `refreshUsers()` after a successful addition, before navigating to the home page. This ensures `usersAtom` fetches fresh data that includes the newly added user. ## Testing User Addition Click **Add User**, fill out the form, and submit. After the redirect, you should see your newly added user in the list. The reactivity system keeps your UI synchronized with your data. For same-page mutations, `reactivityKeys` handles everything automatically. For cross-page mutations, an explicit refresh before navigation ensures the data is up to date. --- In the previous chapter, we used `reactivityKeys` to automatically refresh the user list after deletions, and `useAtomRefresh` to explicitly refresh after additions. These cover most scenarios. But sometimes you need more control. Perhaps you want to invalidate based on a condition, or trigger a refresh from a component after some user interaction that isn't tied to a specific mutation. For these cases, you can create an invalidation Atom. ## Creating an Invalidation Atom In `atoms/user.ts`, add the `invalidateUsersAtom`: ```ts collapse={8-45} ins={2, 47-52} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` This creates a function Atom that, when called, invalidates all Atoms tagged with the `"users"` key. Keep in mind that, like `reactivityKeys`, this uses the reactivity system and only reaches Atoms with active subscribers. ## Using Manual Invalidation To see how this works, let's temporarily use manual invalidation for the user deletion flow. First, comment out the `reactivityKeys` option on `deleteUserAtom` in `atoms/user.ts`: ```ts collapse={8-28, 39-52} title="atoms/user.ts" {36} import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; // ============ Users Atom ============ export const usersAtom = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), // { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` Now in `components/user-delete-dialog.tsx`, import and call the invalidation Atom after a successful deletion: ```ts ins={21, 35, 53} collapse={67-102} title="components/user-delete-dialog.tsx" "use client"; import { useState } from "react"; import { useAtomSet } from "@effect/atom-react"; import { Cause, Exit, Option } from "effect"; import { toast } from "sonner"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger, } from "@/components/ui/dialog"; import { deleteUserAtom, invalidateUsersAtom } from "@/atoms/user"; import type { User } from "@/schema/user-schema"; interface UserDeleteDialogProps { user: User; trigger: React.ReactNode; } export function UserDeleteDialog({ user, trigger }: UserDeleteDialogProps) { const [open, setOpen] = useState(false); const [isDeleting, setIsDeleting] = useState(false); const [error, setError] = useState(null); const deleteUser = useAtomSet(deleteUserAtom, { mode: "promiseExit" }); const invalidateUsers = useAtomSet(invalidateUsersAtom); function handleOpenChange(isOpen: boolean) { setOpen(isOpen); if (!isOpen) { setError(null); } } async function handleDelete() { setIsDeleting(true); setError(null); const exit = await deleteUser(user.id); setIsDeleting(false); if (Exit.isSuccess(exit)) { invalidateUsers(undefined); setOpen(false); toast.success("User deleted successfully", { description: `${user.firstName} ${user.lastName} has been deleted.`, }); } else { const failureOption = Cause.findErrorOption(exit.cause); const errorMessage = Option.isSome(failureOption) ? failureOption.value.message : "An unexpected error occurred"; setError(errorMessage); } } return ( ); } ``` We call `invalidateUsers(undefined)` after confirming the deletion succeeded. `useAtomSet` always returns a setter function that expects one argument, which is the input to the function Atom. With `deleteUserAtom`, that argument is the user ID. With `addUserAtom`, it's the form data. But `invalidateUsersAtom` doesn't need any input; it just triggers an invalidation. Since the setter function still requires an argument, we pass `undefined` to satisfy it. Now, delete a user. The user list should update automatically, just as it did before with `reactivityKeys`. The difference is that this time, the invalidation is triggered manually by calling `invalidateUsersAtom` after the deletion succeeds, rather than being handled automatically by the reactivity system. ## Automatic vs Manual Invalidation For same-page mutations, automatic invalidation via `reactivityKeys` is the right fit. For cross-page mutations, `useAtomRefresh` handles it directly. Manual invalidation via `invalidateUsersAtom` is useful when you need to refresh data based on events that aren't tied to a mutation Atom. For example, a 'Refresh' button, or after a complex multi-step workflow where you only want to invalidate at the end. Since automatic invalidation is the right choice here, let's revert our changes. In `atoms/user.ts`, **uncomment the `reactivityKeys` option on `deleteUserAtom`**. Then in `components/user-delete-dialog.tsx`, **remove the `invalidateUsersAtom` import and the `invalidateUsers()` call**. The `reactivityKeys` on `deleteUserAtom` already handles the invalidation. Keep the `invalidateUsersAtom` definition in `atoms/user.ts` though. It's a useful reference for when you need manual control in the future. --- import { Note } from "@/components/note"; Users often switch between browser tabs while working. When they return to your app, they might be looking at stale data. Effect Atom provides `Atom.refreshOnWindowFocus` to handle this. When the browser window regains focus, the Atom automatically refetches its data. Our app doesn't strictly need this feature because the users' data doesn't change frequently. Window focus refresh is most useful in apps where data changes frequently, such as a dashboard displaying live metrics. But it's a common pattern worth knowing, so let's learn how to set it up. Our app has two Atoms that fetch data: `usersAtom` (used on the home page) and `userAtom` (used on the user detail page). Let's wrap both with `Atom.refreshOnWindowFocus`. ## Adding Window Focus Refresh to `usersAtom` Update `atoms/user.ts` as shown below: ```ts collapse={24-58} title="atoms/user.ts" {8-22} import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; const baseUsersAtom = atomRuntime .atom(() => Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ Users Atom ============ export const usersAtom = ( typeof window !== "undefined" ? Atom.refreshOnWindowFocus(baseUsersAtom) : baseUsersAtom ).pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))), ); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` We split the Atom into two parts. First, we create `baseUsersAtom` with our existing configuration. Then we conditionally wrap it with `Atom.refreshOnWindowFocus`. Why the `typeof window !== "undefined"` check? In Next.js, client components aren't exclusively browser-side. When a page first loads, Next.js renders client components on the server to generate the initial HTML. Since `window` is a browser API that doesn't exist on the server, `Atom.refreshOnWindowFocus` — which listens for browser focus events — would fail during server-side rendering. The check ensures we only apply the window focus behavior in the browser. On the server, we use the base Atom as-is. Note that the exported name remains `usersAtom`, so nothing changes for the components or derived Atoms that depend on it. ## Adding Window Focus Refresh to `usersAtom` We apply the same pattern to `userAtom` so that the user detail page also refreshes when the user switches back to the tab. ```ts collapse={1-22, 38-60} title="atoms/user.ts" {25-36} import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; const baseUsersAtom = atomRuntime .atom(() => Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUsers(); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ Users Atom ============ export const usersAtom = ( typeof window !== "undefined" ? Atom.refreshOnWindowFocus(baseUsersAtom) : baseUsersAtom ).pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => { const base = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); return typeof window !== "undefined" ? Atom.refreshOnWindowFocus(base) : base; }); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` The conditional wrapping happens inside `Atom.family,` so each user's Atom instance gets the window focus behavior individually. ## Testing Window Focus Refresh To see this in action: - Go to the home page and wait for the users to load - Open and move to another browser tab - Come back to your app's tab Now, open the `Network` tab open in your browser's dev tools, and you'll see a new request fire to the `/users` endpoint. The data is being refetched in the background. Now test the detail page. Click the **View details** link on any user card, switch to another tab, and return. You'll see a request to the individual user's endpoint. But from the user's perspective, there's no indication that a refresh is happening. The page looks exactly the same during the refetch. For a better experience, we should provide a visual cue — like dimming the existing content — so users know fresh data is on its way. In the next chapter, we'll learn how to use the `waiting` flag that Effect Atom provides for this purpose. --- import { Note } from "@/components/note"; In the previous chapter, we saw that switching to another tab and returning triggers a data refetch. But from the user's perspective, there's no indication that a refresh is happening. The page looks exactly the same. A common pattern for this scenario is to dim the existing content, giving users a subtle visual cue that fresh data is on its way. ## The `waiting` Flag When an effectful Atom refetches, `useAtomSuspense` does **not** suspend again by default. The component keeps rendering with the previous data while fresh data loads in the background. This is the behavior we want, but we need a way to know that a refetch is in progress. The result returned by `useAtomSuspense` has a `waiting` property. When `waiting` is `true`, the Atom is refetching in the background. When the fetch completes, `waiting` becomes `false`. If you'd prefer the component to suspend during refetches — showing the Suspense fallback instead of stale data — you can pass `{ suspendOnWaiting: true }` to `useAtomSuspense`. This is useful when you want to guarantee users always see completely fresh data. For our app, we'll keep showing stale data with a visual indicator. ## Updating the User Grid Update `components/user-grid-suspense.tsx` to pass the `waiting` boolean to each card: ```tsx title="components/user-grid-suspense.tsx" {26} "use client"; import { useAtomRefresh, useAtomSuspense } from "@effect/atom-react"; import { Cause } from "effect"; import { FailureCard } from "@/components/failure-card"; import { UserSuccessCard } from "@/components/user-success-card"; import { getErrorInfo } from "@/lib/utils"; import { usersAtom } from "@/atoms/user"; export function UserGridSuspense() { const result = useAtomSuspense(usersAtom, { includeFailure: true }); const refresh = useAtomRefresh(usersAtom); if (result._tag === "Failure") { const error = Cause.squash(result.cause); const { title, message } = getErrorInfo(error); return ; } return (

{result.value.users.map((user) => ( ))}

); } ``` `result.waiting` is `true` whenever the Atom is refetching in the background. We pass it to each `UserSuccessCard`, which is already configured to reduce its opacity when `waiting` is `true`. ## Testing the User Grid 1. Navigate to the home page and wait for the users to load. 2. Switch to a different browser tab. 3. Switch back to your app's tab. You'll see the user cards briefly dim as the data refetches. Once the fresh data arrives, the cards return to full opacity. ## Updating the User Detail Page The same pattern applies to the user detail page. On this page, we render the `UserDetail` component, which uses `AsyncResult.builder` to handle the different states. In the `onSuccess` handler, the second parameter is the `AsyncResult` itself, which includes the `waiting` boolean. Update `components/user-detail.tsx` to extract `waiting` and pass it to `UserDetailsCard`: ```tsx title="components/user-detail.tsx" {28-30} "use client"; import { useParams } from "next/navigation"; import { useAtomValue } from "@effect/atom-react"; import { AsyncResult } from "effect/unstable/reactivity"; import { FailureCard } from "@/components/failure-card"; import { UserDetailsCard } from "@/components/user-details-card"; import { UserGridSpinner } from "@/components/user-grid-spinner"; import { getErrorInfo } from "@/lib/utils"; import { userAtom } from "@/atoms/user"; export function UserDetail() { const params = useParams<{ id: string }>(); const result = useAtomValue(userAtom(params.id)); return AsyncResult.builder(result) .onInitial(() => ) .onError((error) => { const { title, message } = getErrorInfo(error); return ; }) .onDefect((defect) => { const { title, message } = getErrorInfo(defect); return ; }) .onSuccess((user, { waiting }) => ( )) .render(); } ``` Like `UserSuccessCard`, `UserDetailsCard` is already configured to reduce its opacity when `waiting` is true. ## Testing the User Detail Page 1. Click on any user card to navigate to their detail page. 2. Wait for the user details to load. 3. Switch to a different browser tab. 4. Switch back to your app's tab. You'll see the user details card dim briefly as the data refetches, then return to full opacity when the fresh data arrives. --- 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: ```ts ins={32, 35} collapse={64-124} title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UserSchema, UsersSchema, type AddUserFormValues, type User, type UsersResponse, } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers(page: number): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ _page: page.toString(), _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Get User ============ function getUser(id: string): Effect.Effect { return client.get(`${apiBaseUrl}/users/${id}`).pipe( Effect.delay("1 second"), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Delete User ============ function deleteUser(userId: string): Effect.Effect { return client.del(`${apiBaseUrl}/users/${userId}`).pipe( Effect.delay("1 second"), Effect.asVoid, Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), ); } // ============ Add User ============ function addUser( user: AddUserFormValues, ): Effect.Effect { return HttpClientRequest.post(`${apiBaseUrl}/users`).pipe( HttpClientRequest.bodyJson(user), Effect.delay("1 second"), Effect.flatMap(client.execute), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } return { getUsers, getUser, deleteUser, addUser }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` 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: ```ts title="atoms/page.ts" import { Atom } from "effect/unstable/reactivity"; export const pageQueryParamAtom = Atom.searchParam( "page", ) as unknown as Atom.Writable; export const pageAtom = Atom.writable( (get) => { const rawPage = get(pageQueryParamAtom); if (rawPage === "") { return 1; } const parsedPage = Number(rawPage); if (!Number.isInteger(parsedPage) || parsedPage < 1) { return 1; } return parsedPage; }, (ctx, page: number) => { const nextPage = Math.max(1, Math.floor(page)); if (nextPage === 1) { ctx.set(pageQueryParamAtom, ""); } else { ctx.set(pageQueryParamAtom, String(nextPage)); } }, ); ``` 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). URL query parameters are always strings, so `pageQueryParamAtom` holds a raw string value. When the URL contains `?page=2`, the Atom's value is `"2"`. When there's no `?page=` parameter, the Atom's value is an empty string `""`. We could use `pageQueryParamAtom` directly in our components, but working with raw strings everywhere would be inconvenient. We'd need to parse the string into a number every time we read the value, handle the empty string case, and convert numbers back to strings 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, which lets you read other Atoms. Here, we use `get(pageQueryParamAtom)` to read the current URL parameter as a raw string. If the string is empty (no `?page=` in the URL), we default to `1`. Otherwise, we parse it into a number. If the parsed value isn't a valid positive integer, we fall back to `1` as a safeguard. This means components can work with a plain number instead of dealing with string parsing. **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 an empty string, 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 convert the number to a string and set it, which adds `?page=2`, `?page=3`, etc. to the URL. ## Updating the Users Atom Update `baseUsersAtom` in `atoms/user.ts` to use the page: ```ts ins={5, 12} collapse={19-62} title="atoms/user.ts" {10, 14} import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { pageAtom } from "@/atoms/page"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; const baseUsersAtom = atomRuntime .atom((get) => Effect.gen(function* () { const page = get(pageAtom); const userService = yield* UserService; return yield* userService.getUsers(page); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ Users Atom ============ export const usersAtom = ( typeof window !== "undefined" ? Atom.refreshOnWindowFocus(baseUsersAtom) : baseUsersAtom ).pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => { const base = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); return typeof window !== "undefined" ? Atom.refreshOnWindowFocus(base) : base; }); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` 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: ```tsx title="components/user-pagination.tsx" "use client"; import { useAtom, useAtomValue } from "@effect/atom-react"; import { AsyncResult, Atom } from "effect/unstable/reactivity"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { USERS_PER_PAGE } from "@/lib/constants"; import { pageAtom } from "@/atoms/page"; import { usersAtom } from "@/atoms/user"; const selectUsersCount = (result: Atom.Type) => AsyncResult.map(result, (data) => data.usersCount); export function UserPagination() { const [page, setPage] = useAtom(pageAtom); const usersCountResult = useAtomValue(usersAtom, selectUsersCount); return AsyncResult.match(usersCountResult, { onInitial: () => null, onFailure: () => null, onSuccess: (result) => { const totalPages = Math.ceil(result.value / USERS_PER_PAGE); if (totalPages <= 1) return null; return (

Page {page} of {totalPages}

); }, }); } ``` This component introduces the `useAtom` hook. While `useAtomValue` only reads and `useAtomSet` only writes, `useAtom` gives you both: ```tsx 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 20 to 8: ```ts title="lib/constants.ts" {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. --- Right now, the home page shows a placeholder text **User Search** above the user grid. Let's replace it with an actual search input and wire up the search logic. ## Updating the `getUsers` Method Update `getUsers` in `services/user-service.ts` to accept a search query parameter: ```ts ins={33, 38} collapse={68-128} title="services/user-service.ts" import { Effect, Layer, ServiceMap } from "effect"; import { FetchHttpClient, HttpClient, HttpClientRequest, HttpClientResponse, } from "effect/unstable/http"; import { apiBaseUrlConfig } from "@/lib/config"; import { USERS_PER_PAGE } from "@/lib/constants"; import { mapHttpError } from "@/lib/http-error"; import { ParseError, type HttpError } from "@/errors"; import { UserSchema, UsersSchema, type AddUserFormValues, type User, type UsersResponse, } from "@/schema/user-schema"; export class UserService extends ServiceMap.Service()( "app/UserService", { make: Effect.gen(function* () { const client = (yield* HttpClient.HttpClient).pipe( HttpClient.filterStatusOk, ); const apiBaseUrl = yield* apiBaseUrlConfig; // ============ Get Users ============ function getUsers( query: string, page: number, ): Effect.Effect { const request = HttpClientRequest.get(`${apiBaseUrl}/users`).pipe( HttpClientRequest.setUrlParams({ q: query, _page: page.toString(), _limit: USERS_PER_PAGE.toString(), }), ); return client.execute(request).pipe( Effect.delay("1 second"), Effect.flatMap((response) => Effect.all({ users: HttpClientResponse.schemaBodyJson(UsersSchema)(response), usersCount: Effect.succeed( Number(response.headers["x-total-count"]), ), }), ), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Get User ============ function getUser(id: string): Effect.Effect { return client.get(`${apiBaseUrl}/users/${id}`).pipe( Effect.delay("1 second"), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } // ============ Delete User ============ function deleteUser(userId: string): Effect.Effect { return client.del(`${apiBaseUrl}/users/${userId}`).pipe( Effect.delay("1 second"), Effect.asVoid, Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), ); } // ============ Add User ============ function addUser( user: AddUserFormValues, ): Effect.Effect { return HttpClientRequest.post(`${apiBaseUrl}/users`).pipe( HttpClientRequest.bodyJson(user), Effect.delay("1 second"), Effect.flatMap(client.execute), Effect.flatMap(HttpClientResponse.schemaBodyJson(UserSchema)), Effect.catchTag("HttpClientError", (error) => Effect.fail(mapHttpError(error)), ), Effect.catchTag("SchemaError", (error) => Effect.fail( new ParseError({ message: "Received an unexpected response from the server.", cause: error, }), ), ), ); } return { getUsers, getUser, deleteUser, addUser }; }), }, ) { static layer = Layer.effect(this, this.make).pipe( Layer.provide(FetchHttpClient.layer), ); } ``` The function now takes a `query` argument, which we pass as the `q` URL parameter. This is what json-server uses for full-text search. When you pass `q=john`, it returns all users where any field contains `"john"`. ## Creating the Search Atom In `atoms/search.ts`, add the following code: ```ts title="atoms/search.ts" import { Option, Schema } from "effect"; import { Atom } from "effect/unstable/reactivity"; const searchQueryParamAtom = Atom.searchParam("q", { schema: Schema.String, }); export const searchQueryAtom = Atom.writable( (get) => get(searchQueryParamAtom).pipe(Option.getOrElse(() => "")), (ctx, query: string) => { if (query === "") { ctx.set(searchQueryParamAtom, Option.none()); } else { ctx.set(searchQueryParamAtom, Option.some(query)); } }, ); export const debouncedSearchQueryAtom = searchQueryAtom.pipe( Atom.debounce("300 millis"), ); ``` This follows the same pattern we used for `pageAtom`. The low-level `searchQueryParamAtom` uses `Atom.searchParam` with `Schema.String` and returns an `Option`. When the q parameter is missing from the URL, it's `None`. When present, it's `Some`. The exported `searchQueryAtom` wraps this with `Atom.writable` to provide a cleaner string interface. The read side unwraps the `Option`, defaulting to an empty string when the parameter is absent. The write side sets `Option.none()` for empty strings (which removes the `q` parameter from the URL) and `Option.some(query)` otherwise. ## Atom.debounce `Atom.debounce()` creates a debounced version of an Atom. When the source Atom changes, the debounced Atom waits for the specified duration before updating. If another change occurs during that wait, the timer resets. This is essential for search. Without debouncing, every keystroke triggers an API request. Type "john" and you'd fire four requests: "j", "jo", "joh", "john". With a 300ms debounce, we only fire one request after the user stops typing. ## Updating the Users Atom Update `baseUsersAtom` in `atoms/user.ts` to use the query: ```ts ins={6, 14, 16} collapse={21-64} title="atoms/user.ts" import { Duration, Effect } from "effect"; import { Atom, Reactivity } from "effect/unstable/reactivity"; import { atomRuntime } from "@/atom-runtime"; import { pageAtom } from "@/atoms/page"; import { debouncedSearchQueryAtom } from "@/atoms/search"; import { type AddUserFormValues } from "@/schema/user-schema"; import { UserService } from "@/services/user-service"; const baseUsersAtom = atomRuntime .atom((get) => Effect.gen(function* () { const page = get(pageAtom); const query = get(debouncedSearchQueryAtom); const userService = yield* UserService; return yield* userService.getUsers(query, page); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ Users Atom ============ export const usersAtom = ( typeof window !== "undefined" ? Atom.refreshOnWindowFocus(baseUsersAtom) : baseUsersAtom ).pipe(Atom.setIdleTTL(Duration.hours(1)), Atom.withReactivity(["users"])); // ============ User Atom ============ export const userAtom = Atom.family((id: string) => { const base = atomRuntime .atom( Effect.gen(function* () { const userService = yield* UserService; return yield* userService.getUser(id); }), ) .pipe(Atom.setIdleTTL(Duration.hours(1))); return typeof window !== "undefined" ? Atom.refreshOnWindowFocus(base) : base; }); // ============ Delete User Atom ============ export const deleteUserAtom = atomRuntime.fn( Effect.fnUntraced(function* (userId: string) { const userService = yield* UserService; yield* userService.deleteUser(userId); }), { reactivityKeys: ["users"] }, ); // ============ Add User Atom ============ export const addUserAtom = atomRuntime.fn()( Effect.fnUntraced(function* (user) { const userService = yield* UserService; return yield* userService.addUser(user); }), ); // ============ Invalidate Users Atom ============ export const invalidateUsersAtom = atomRuntime.fn()( Effect.fnUntraced(function* () { yield* Reactivity.invalidate(["users"]); }), ); ``` ## Updating the Search Bar Replace the code inside `components/user-search-bar.tsx` with the following: ```tsx title="components/user-search-bar.tsx" "use client"; import { useAtom, useAtomSet } from "@effect/atom-react"; import { pageAtom } from "@/atoms/page"; import { searchQueryAtom } from "@/atoms/search"; import { Icons } from "@/components/icons"; import { Button } from "@/components/ui/button"; import { Input } from "@/components/ui/input"; export function UserSearchBar() { const [query, setQuery] = useAtom(searchQueryAtom); const setPage = useAtomSet(pageAtom); function handleChange(e: React.ChangeEvent) { setQuery(e.target.value); setPage(1); } function handleClear() { setQuery(""); setPage(1); } function handleKeyDown(e: React.KeyboardEvent) { if (e.key === "Escape") { handleClear(); } } return (

{query && ( )}

); } ``` The component is a controlled input driven by `searchQueryAtom`. We use `useAtom` to get both the current search query and its setter, making the input's value always reflect the URL's `q` parameter. The `handleChange` function does two things whenever the user types. It updates the search query atom with the new input value, and it resets the page back to 1. Resetting the page is important because search results change the total number of available pages. If you're on page 3 and search for something that only has one page of results, staying on page 3 would show no results even though matches exist. For clearing the search, we provide two mechanisms. Clicking the `ESC` button or pressing the Escape key both call `handleClear`, which sets the query to an empty string and resets the page. Notice that we don't debounce anything in this component. The input updates `searchQueryAtom` on every keystroke, so the URL's `q` parameter and the input value stay perfectly in sync. The debouncing happens one layer deeper: `baseUsersAtom` reads from `debouncedSearchQueryAtom`, which waits 300ms after the last change before updating. This separation means the user sees their typing reflected immediately in both the input and the URL, while the expensive API call only fires once they pause. When the user types, we update the search query and reset to page 1. It doesn't make sense to stay on page 3 when search results might only have one page. ## Updating the `UserGridSuspense` Component Previously, when the users list was empty, `UserGridSuspense` rendered the grid with zero cards and no message. That was fine before search existed, but now there are three distinct reasons why no users might appear: the search query matched nothing, the page number exceeds the available pages, or the list is genuinely empty. The `getNoUsersFoundReason` helper in `user-empty-card.tsx` already handles this logic. We just need to give it the information it needs. Update `components/user-grid-suspense.tsx` as shown below: ```tsx ins={6, 11-14, 18-19, 25-26, 35-45} title="components/user-grid-suspense.tsx" {49} "use client"; import { useAtomRefresh, useAtomSuspense, useAtomValue, } from "@effect/atom-react"; import { Cause } from "effect"; import { FailureCard } from "@/components/failure-card"; import { getNoUsersFoundReason, UserEmptyCard, } from "@/components/user-empty-card"; import { UserSuccessCard } from "@/components/user-success-card"; import { getErrorInfo } from "@/lib/utils"; import { pageAtom } from "@/atoms/page"; import { debouncedSearchQueryAtom } from "@/atoms/search"; import { usersAtom } from "@/atoms/user"; export function UserGridSuspense() { const result = useAtomSuspense(usersAtom, { includeFailure: true }); const refresh = useAtomRefresh(usersAtom); const searchQuery = useAtomValue(debouncedSearchQueryAtom); const page = useAtomValue(pageAtom); if (result._tag === "Failure") { const error = Cause.squash(result.cause); const { title, message } = getErrorInfo(error); return ; } const users = result.value.users; if (users.length === 0) { const reason = getNoUsersFoundReason(users, searchQuery, page); return reason === "page-out-of-range" ? ( ) : ( ); } return (

{users.map((user) => ( ))}

); } ``` We read `debouncedSearchQueryAtom` and `pageAtom` via `useAtomValue`, then check whether the result array is empty before rendering the grid. If it is, we pass the users, search query, and page to `getNoUsersFoundReason`, which determines the appropriate message. If the search query is non-empty, it returns `"no-matching-search-results"`. If the page is greater than 1 with no search query, it returns `"page-out-of-range"`. Otherwise, it falls back to `"empty-users-list"`. ## Testing Search Type the name of a user in the search bar. After a brief delay (the 300ms debounce), the user list filters to match your query. The URL updates to include the search parameter (e.g., `?q=emma`). If nothing matches the search query, you'll see a message indicating no users were found. --- You can find the source code of the application we built in this course on GitHub: Final app after free chapters: [https://github.com/sundaray/effect-atom-start/tree/completed-free](https://github.com/sundaray/effect-atom-start/tree/completed-free) Final app after all chapters: [https://github.com/sundaray/effect-atom-start/tree/completed-paid](https://github.com/sundaray/effect-atom-start/tree/completed-paid) If you want to clone the project locally, you can choose the branch that matches your progress through the course. To clone the version of the app as it stands at the end of free chapters, run: ```bash git clone -b completed-free https://github.com/sundaray/effect-atom-start.git ``` To clone the version of the app as it stands at the end of the complete course, run: ```bash git clone -b completed-paid https://github.com/sundaray/effect-atom-start.git ``` --- I hope you found the course useful. You should now have a solid understanding of the Effect Atom APIs used to manage server state in React. The best way to solidify your knowledge further is to start using Effect Atom in your own projects. See you in the next course.

Stay in the loop