Agent skill

State Management

This skill should be used when the user asks about "Effect Ref", "mutable state", "Ref.make", "Ref.get", "Ref.set", "Ref.update", "SubscriptionRef", "SynchronizedRef", "reactive state", "state updates", "concurrent state", "shared mutable state", or needs to understand how Effect handles mutable state in a functional way.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/state-management

SKILL.md

State Management in Effect

Overview

Effect provides functional mutable state primitives:

  • Ref - Basic mutable reference
  • SynchronizedRef - Ref with effectful updates
  • SubscriptionRef - Ref with change notifications

All are fiber-safe and work correctly with concurrent access.

Ref - Basic Mutable Reference

Creating and Using Refs

typescript
import { Effect, Ref } from "effect"

const program = Effect.gen(function* () {
  const counter = yield* Ref.make(0)

  const current = yield* Ref.get(counter)

  yield* Ref.set(counter, 10)

  yield* Ref.update(counter, (n) => n + 1)

  const old = yield* Ref.getAndSet(counter, 0)

  const newValue = yield* Ref.updateAndGet(counter, (n) => n + 5)

  const [oldVal, result] = yield* Ref.modify(counter, (n) => [
    n,
    n * 2
  ])
})

Atomic Operations

typescript
const atomicIncrement = Effect.gen(function* () {
  const counter = yield* Ref.make(0)

  yield* Effect.all([
    Ref.update(counter, (n) => n + 1),
    Ref.update(counter, (n) => n + 1),
    Ref.update(counter, (n) => n + 1)
  ], { concurrency: "unbounded" })

  return yield* Ref.get(counter)
})

Ref in Services

typescript
const CounterService = Effect.gen(function* () {
  const ref = yield* Ref.make(0)

  return {
    increment: Ref.update(ref, (n) => n + 1),
    decrement: Ref.update(ref, (n) => n - 1),
    get: Ref.get(ref),
    reset: Ref.set(ref, 0)
  }
})

const CounterLive = Layer.effect(Counter, CounterService)

SynchronizedRef - Effectful Updates

For updates that require running effects:

typescript
import { Effect, SynchronizedRef } from "effect"

const program = Effect.gen(function* () {
  const ref = yield* SynchronizedRef.make({ count: 0, lastUpdated: Date.now() })

  yield* SynchronizedRef.updateEffect(ref, (state) =>
    Effect.gen(function* () {
      yield* Effect.log("Updating state")
      return {
        count: state.count + 1,
        lastUpdated: Date.now()
      }
    })
  )

  const result = yield* SynchronizedRef.modifyEffect(ref, (state) =>
    Effect.gen(function* () {
      const newCount = state.count + 1
      yield* sendMetric("counter", newCount)
      return [
        newCount,
        { ...state, count: newCount }
      ]
    })
  )
})

When to Use SynchronizedRef

  • Updates require API calls
  • Updates require logging/metrics
  • Updates depend on external state
  • Updates need error handling
typescript
// Cache with async refresh
const cache = yield* SynchronizedRef.make<Data | null>(null)

const refreshCache = SynchronizedRef.updateEffect(cache, () =>
  Effect.tryPromise(() => fetchLatestData())
)

SubscriptionRef - Reactive State

For state that needs to notify subscribers:

typescript
import { Effect, SubscriptionRef, Stream } from "effect"

const program = Effect.gen(function* () {
  const ref = yield* SubscriptionRef.make(0)

  const changes = yield* SubscriptionRef.changes(ref)

  yield* Effect.fork(
    Stream.runForEach(changes, (value) =>
      Effect.log(`Value changed to: ${value}`)
    )
  )

  yield* SubscriptionRef.set(ref, 1)
  yield* SubscriptionRef.update(ref, (n) => n + 1)
  yield* SubscriptionRef.set(ref, 10)
})

Reactive Patterns

typescript
const configRef = yield* SubscriptionRef.make(initialConfig)

const subscriber1 = Effect.fork(
  Stream.runForEach(
    SubscriptionRef.changes(configRef),
    (config) => updateService1(config)
  )
)

const subscriber2 = Effect.fork(
  Stream.runForEach(
    SubscriptionRef.changes(configRef),
    (config) => updateService2(config)
  )
)

yield* SubscriptionRef.set(configRef, newConfig)

Comparison

Feature Ref SynchronizedRef SubscriptionRef
Basic get/set ✅ ✅ ✅
Atomic updates ✅ ✅ ✅
Effectful updates ❌ ✅ ❌
Change notifications ❌ ❌ ✅
Use case Simple state Async updates Reactive state

Common Patterns

Counter Service

typescript
class Counter extends Context.Tag("Counter")<
  Counter,
  {
    readonly increment: Effect.Effect<number>
    readonly decrement: Effect.Effect<number>
    readonly get: Effect.Effect<number>
  }
>() {}

const CounterLive = Layer.effect(
  Counter,
  Effect.gen(function* () {
    const ref = yield* Ref.make(0)
    return {
      increment: Ref.updateAndGet(ref, (n) => n + 1),
      decrement: Ref.updateAndGet(ref, (n) => n - 1),
      get: Ref.get(ref)
    }
  })
)

State Machine

typescript
type State = "idle" | "loading" | "success" | "error"

const stateMachine = Effect.gen(function* () {
  const state = yield* Ref.make<State>("idle")

  const transition = (from: State, to: State) =>
    Ref.modify(state, (current) =>
      current === from
        ? [true, to]
        : [false, current]
    )

  return {
    state: Ref.get(state),
    startLoading: transition("idle", "loading"),
    succeed: transition("loading", "success"),
    fail: transition("loading", "error"),
    reset: Ref.set(state, "idle")
  }
})

Accumulator

typescript
const accumulator = Effect.gen(function* () {
  const items = yield* Ref.make<Array<Item>>([])

  return {
    add: (item: Item) => Ref.update(items, (arr) => [...arr, item]),
    getAll: Ref.get(items),
    clear: Ref.set(items, []),
    count: Effect.map(Ref.get(items), (arr) => arr.length)
  }
})

Best Practices

  1. Use Ref for simple state - Basic counters, flags, accumulators
  2. Use SynchronizedRef for async updates - When updates need effects
  3. Use SubscriptionRef for reactive patterns - When others need notifications
  4. Keep state minimal - Don't store derived data
  5. Prefer immutable updates - Return new objects, don't mutate

Additional Resources

For comprehensive state management documentation, consult ${CLAUDE_PLUGIN_ROOT}/references/llms-full.txt.

Search for these sections:

  • "Ref" for basic mutable references
  • "SynchronizedRef" for effectful updates
  • "SubscriptionRef" for reactive state

Didn't find tool you were looking for?

Be as detailed as possible for better results