state

name	state
description	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.
version	1.0.0

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

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

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

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:

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

// 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:

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

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

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

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

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