TxRef
Transactional references for coordinating mutable state with Effect transactions. A TxRef stores a current value, but reads and writes inside Effect.tx are recorded in a transaction journal and committed together only when the outermost transaction succeeds.
This is the basic building block behind the other transactional collections in Effect. The module provides effectful and unsafe constructors plus the core operations for reading, setting, updating, and modifying a transactional value while returning a separate result.
Combinators
Signature
declare function get<A>(self: TxRef<A>): Effect<A>;Modifies the value of the TxRef using the provided function.
When to use
Use to update a TxRef and return a computed result from the same transaction step.
Signature
declare const modify: {
<A, R>(f: (current: NoInfer<A>) => [returnValue: R, newValue: A]): (self: TxRef<A>) => Effect<R>;
<A, R>(self: TxRef<A>, f: (current: A) => [returnValue: R, newValue: A]): Effect<R>;
};Sets the value of the TxRef.
When to use
Use to replace the value of a TxRef.
Signature
declare const set: {
<A>(value: A): (self: TxRef<A>) => Effect<void>;
<A>(self: TxRef<A>, value: A): Effect<void>;
};Updates the value of the TxRef using the provided function.
When to use
Use to transform a TxRef when no result value is needed.
Signature
declare const update: {
<A>(f: (current: NoInfer<A>) => A): (self: TxRef<A>) => Effect<void>;
<A>(self: TxRef<A>, f: (current: A) => A): Effect<void>;
};Constructors
Creates a new TxRef with the specified initial value.
When to use
Use to create a TxRef inside an Effect workflow.
Signature
declare function make<A>(initial: A): Effect<TxRef<A>, never, never>;makeUnsafe
Creates a new TxRef synchronously with the specified initial value.
When to use
Use to construct a TxRef synchronously when it must be created outside an Effect workflow.
Signature
declare function makeUnsafe<A>(initial: A): TxRef<A>;Models
TxRef is a transactional value, it can be read and modified within the body of a transaction.
When to use
Use to store mutable state that must be read and modified inside Effect transactions.
Details
Accessed values are tracked by the transaction in order to detect conflicts and in order to track changes, a transaction will retry whenever a conflict is detected or whenever the transaction explicitely calls to Effect.txRetry and any of the accessed TxRef values change.
Signature
interface TxRef<in out A> extends Pipeable {
readonly "~effect/transactions/TxRef": "~effect/transactions/TxRef";
pending: Map<unknown, () => void>;
value: A;
version: number;
}
Reads the current value of the
TxRef.When to use
Use to read the current value of a
TxRef.