Ref
Stores fiber-safe mutable state inside Effect programs.
A Ref<A> holds one value and exposes reads, writes, and atomic transformations as effects, so state changes compose with Effect's concurrency model. This module includes constructors, safe and unsafe reads, set and get-and-set helpers, update and modify helpers, and conditional update variants that leave the value unchanged when an Option.none result is returned.
Constructors
Signature
declare function make<A>(value: A): Effect<Ref<A>>;makeUnsafe
Creates a new Ref with the specified initial value (unsafe version).
When to use
Use when you need immediate synchronous construction and can guarantee that creating the Ref outside of Effect is safe.
Gotchas
Prefer Ref.make for Effect-wrapped creation in Effect programs.
Signature
declare function makeUnsafe<A>(value: A): Ref<A>;Getters
Gets the current value of the Ref.
When to use
Use to read the current Ref value without changing it.
See
setfor replacing the current value
Signature
declare function get<A>(self: Ref<A>): Effect<A, never, never>;Gets the current value of the Ref synchronously (unsafe version).
When to use
Use when you need immediate synchronous access and can guarantee that reading the Ref outside of Effect is safe.
Gotchas
Prefer Ref.get for Effect-wrapped access in Effect programs.
Signature
declare function getUnsafe<A>(self: Ref<A>): A;Models
A mutable reference that provides atomic read, write, and update operations.
When to use
Use to keep shared mutable state that is read and updated inside Effect programs.
Details
A Ref is a thread-safe mutable reference type for shared state. It supports simple read and write operations as well as atomic transformations.
See
Signature
interface Ref<in out A> extends Variance<A>, Pipeable {
readonly ref: MutableRef<A>;
}Mutations
Gets the current value of the Ref, sets it to the specified value, and returns the previous value atomically.
When to use
Use to replace a plain Ref value while returning the previous value.
See
setfor setting without returning the previous valuegetAndUpdatefor deriving the new value from the previous value
Signature
declare const getAndSet: <A>(value: A) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, value: A) => Effect<A>getAndUpdate
Gets the current value of the Ref, updates it with the given function, and returns the previous value atomically.
When to use
Use to derive a new Ref value while returning the previous value.
See
updatefor updating without returning the previous valueupdateAndGetfor returning the new value instead
Signature
declare const getAndUpdate: <A>(f: (a: A) => A) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, f: (a: A) => A) => Effect<A>getAndUpdateSome
Gets the current value of the Ref and updates it atomically with the given partial function.
When to use
Use to return the previous Ref value while applying a conditional update.
Details
If the partial function returns Option.some, the Ref is updated with the new value. If it returns Option.none, the Ref is left unchanged. The effect always returns the value that was in the Ref before the attempted update.
See
getAndUpdatefor always applying an updateupdateSomefor conditional updates without returning the previous value
Signature
declare const getAndUpdateSome: <A>(pf: (a: A) => Option<A>) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, pf: (a: A) => Option<A>) => Effect<A>Modifies the value of the Ref atomically using the given function.
When to use
Use to compute both a separate return value and the next stored Ref value in one atomic update.
Details
The function receives the current value and returns a tuple of [result, newValue]. The Ref is updated with newValue, and result is returned by the effect.
See
updateAndGetfor returning the new stored valuemodifySomefor optionally updating while returning a separate result
Signature
declare const modify: <A, B>(f: (a: A) => readonly [B, A]) => (self: Ref<A>) => Effect<B> & <A, B>(self: Ref<A>, f: (a: A) => readonly [B, A]) => Effect<B>modifySome
Computes a result atomically and optionally updates the value of the Ref.
When to use
Use to compute a return value while optionally updating a plain Ref.
Details
The callback receives the current value and returns [result, nextValue], where nextValue is an Option. If nextValue is Option.some(value), the Ref is updated to value; if it is Option.none(), the Ref is left unchanged. The returned effect always succeeds with result.
See
modifyfor always storing a new valueupdateSomefor optional updates without a separate return value
Signature
declare const modifySome: {
<B, A>(pf: (a: A) => readonly [B, Option<A>]): (self: Ref<A>) => Effect<B>;
<A, B>(self: Ref<A>, pf: (a: A) => readonly [B, Option<A>]): Effect<B>;
};Sets the value of the Ref to the specified value.
When to use
Use to replace the current Ref value with a known value.
See
Signature
declare const set: <A>(value: A) => (self: Ref<A>) => Effect<void> & <A>(self: Ref<A>, value: A) => Effect<void>Sets the value of the Ref atomically to the specified value and returns the new value.
When to use
Use when you want to set a Ref value and immediately get it back in one atomic operation.
Signature
declare const setAndGet: <A>(value: A) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, value: A) => Effect<A>Updates the value of the Ref atomically using the given function.
When to use
Use to apply a Ref state transition without returning a value.
See
updateAndGetfor returning the new valuegetAndUpdatefor returning the previous value
Signature
declare const update: <A>(f: (a: A) => A) => (self: Ref<A>) => Effect<void> & <A>(self: Ref<A>, f: (a: A) => A) => Effect<void>updateAndGet
Updates the value of the Ref atomically using the given function and returns the new value.
When to use
Use to apply a Ref state transition and return the new stored value.
See
updatefor updating without returning the new valuegetAndUpdatefor returning the previous value instead
Signature
declare const updateAndGet: <A>(f: (a: A) => A) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, f: (a: A) => A) => Effect<A>updateSome
Updates the value of the Ref atomically using the given partial function.
When to use
Use to apply a conditional Ref update without returning a value.
Details
If the partial function returns Option.some, the Ref is updated with the new value. If it returns Option.none, the Ref is left unchanged.
See
updatefor always applying an updateupdateSomeAndGetfor returning the resulting current value
Signature
declare const updateSome: <A>(f: (a: A) => Option<A>) => (self: Ref<A>) => Effect<void> & <A>(self: Ref<A>, f: (a: A) => Option<A>) => Effect<void>updateSomeAndGet
Updates the value of the Ref atomically using the given partial function and returns the current value.
When to use
Use to apply a conditional Ref update and return the resulting current value.
Details
If the partial function returns Option.some, the Ref is updated with the new value. If it returns Option.none, the Ref is left unchanged. The effect returns the current value of the Ref after the potential update.
See
updateSomefor conditional updates without returning a valueupdateAndGetfor always updating and returning the new value
Signature
declare const updateSomeAndGet: <A>(pf: (a: A) => Option<A>) => (self: Ref<A>) => Effect<A> & <A>(self: Ref<A>, pf: (a: A) => Option<A>) => Effect<A>
Creates a new Ref with the specified initial value.
When to use
Use to create a
Reffor shared mutable state inside an Effect program.See
makeUnsafefor synchronous construction outside Effect code