effect-atom

Atoms can be backed by Effect Streams:

• Standard Stream Atom: Atom.make(stream) creates an Atom that always holds the latest value emitted by the stream as a Result.
• Pull Atom: Atom.pull(stream) creates a Writable Atom that allows you to pull chunks of data from a stream one at a time (useful for infinite scrolling). Use useAtom in React to get both the result and a pull function.

import { Atom, Result, useAtom } from "@effect-atom/atom-react"
import { Cause, Schedule, Stream } from "effect"

// Emits incrementing number every second
const countAtom = Atom.make(Stream.fromSchedule(Schedule.spaced(1000)))

// Pull-based Atom for paginated data
const countPullAtom = Atom.pull(Stream.make(1, 2, 3, 4, 5))

function CountPullAtomComponent() {
  const [result, pull] = useAtom(countPullAtom)

  return Result.builder(result)
    .onInitial(() => <div>Loading...</div>)
    .onFailure((cause) => <div>Error: {Cause.pretty(cause)}</div>)
    .onSuccess(({ items }, { waiting }) => (
      <div>
        <ul>{items.map((item) => <li key={item}>{item}</li>)}</ul>
        <button onClick={() => pull()}>Load more</button>
        {waiting ? <p>Loading more...</p> : <p>Loaded chunk</p>}
      </div>
    ))
    .render()
}

The AtomHttpApi module allows you to create an HTTP API client that integrates with effect-atom. This enables you to use HTTP endpoints as reactive atoms.

Key Workflow:

1. Define the API: Use HttpApi.make and HttpApiEndpoint to define your endpoints, methods, paths, and success schemas.
2. Create the Client Tag: Use AtomHttpApi.Tag to create a specialized Context.Tag. You must provide the api definition, an httpClient (e.g., FetchHttpClient.layer), and a baseUrl.
3. Use in Components:
   • Use CountClient.query(groupName, endpointName, options) for read-only data. Use reactivityKeys to enable invalidation.
   • Use CountClient.mutation(groupName, endpointName) for state changes. Mutations can include reactivityKeys to invalidate queries when finished.
4. Use in Effect Services: Add CountClient.layer to your service's dependencies to access the client via yield* CountClient.

import { AtomHttpApi, Result, useAtomSet, useAtomValue } from "@effect-atom/atom-react"
import { FetchHttpClient, HttpApi, HttpApiEndpoint, HttpApiGroup } from "@effect/platform"
import { Effect, Schema } from "effect"

// 1. Define your api
class Api extends HttpApi.make("api").add(
  HttpApiGroup.make("counter").add(
    HttpApiEndpoint.get("count", "/count").addSuccess(Schema.Number)
  ).add(
    HttpApiEndpoint.post("increment", "/increment")
  )
) {}

// 2. Create the Client Tag
class CountClient extends AtomHttpApi.Tag<CountClient>()("CountClient", {
  api: Api,
  httpClient: FetchHttpClient.layer,
  baseUrl: "http://localhost:3000"
}) {}

function SomeComponent() {
  // 3. Use in Components
  const count = useAtomValue(CountClient.query("counter", "count", {
    reactivityKeys: ["count"]
  }))

  const increment = useAtomSet(CountClient.mutation("counter", "increment"))

  return (
    <div onClick={() => increment({ payload: void 0, reactivityKeys: ["count"] })}>
      <p>Count: {Result.getOrElse(count, () => 0)}</p>
    </div>
  )
}

You can use the AtomRpc module to create an RPC client that integrates with effect-atom. This allows you to treat RPC queries and mutations as atoms, providing reactivity and easy integration with React hooks like useAtomValue and useAtomSet.

Key Workflow:

1. Define RPCs: Use RpcGroup.make to define your RPC methods and their success schemas.
2. Create the Client Tag: Use AtomRpc.Tag to create a specialized Context.Tag. You must provide a group (your RPC definitions) and a protocol (a Layer providing the RpcClient.Protocol, such as a WebSocket layer).
3. Use in Components:
   • Use CountClient.query(name, payload, options) for read-only data. Use reactivityKeys to enable invalidation.
   • Use CountClient.mutation(name) for state changes. Mutations can also include reactivityKeys to automatically invalidate related queries upon completion.
4. Use in Effect Services: Add CountClient.layer to your service's dependencies to access the client via yield* CountClient.

import { AtomRpc, Result, useAtomSet, useAtomValue } from "@effect-atom/atom-react"
import { Effect, Layer, Schema } from "effect"
import { BrowserSocket } from "@effect/platform-browser"
import { Rpc, RpcClient, RpcGroup, RpcSerialization } from "@effect/rpc"

// 1. Define the RPCs
class Rpcs extends RpcGroup.make(
  Rpc.make("increment"),
  Rpc.make("count", { success: Schema.Number })
) {}

// 2. Create the Client Tag
class CountClient extends AtomRpc.Tag<CountClient>()("CountClient", {
  group: Rpcs,
  protocol: RpcClient.layerProtocolSocket({
    retryTransientErrors: true
  }).pipe(
    Layer.provide(BrowserSocket.layerWebSocket("ws://localhost:3000/rpc")),
    Layer.provide(RpcSerialization.layerJson)
  )
}) {}

function SomeComponent() {
  // 3. Use in Components
  const count = useAtomValue(CountClient.query("count", void 0, {
    reactivityKeys: ["count"]
  }))

  const increment = useAtomSet(CountClient.mutation("increment"))

  return (
    <div onClick={() => increment({ payload: void 0, reactivityKeys: ["count"] })}>
      <p>Count: {Result.getOrElse(count, () => 0)}</p>
    </div>
  )
}