Skip to content

MutableRef

Stores synchronous mutable state in a small reference object.

A MutableRef<A> stores one current value and exposes it through .current. Unlike Ref, its operations are synchronous and update the same object in place. This module includes pipeable helpers for reading, setting, comparing, and updating the value, plus numeric increment/decrement helpers and a boolean toggle helper.

17 exports Added in v2.0.0 Source

Constructors

make

Added in v2.0.0 Source

Creates a new MutableRef with the specified initial value.

When to use

Use to create a synchronous MutableRef initialized with a value.

Signature

declare function make<T>(value: T): MutableRef<T>;

Getters

get

Added in v2.0.0 Source

Gets the current value of the MutableRef.

When to use

Use to read the current MutableRef value without mutating it.

Signature

declare function get<T>(self: MutableRef<T>): T;

Models

MutableRef interface

Added in v2.0.0 Source

A synchronous mutable reference that stores a current value.

When to use

Use to keep local mutable state in a stable, pipeable reference.

Details

Read or write the value directly through .current, or use the MutableRef helpers for pipeable updates such as get, set, update, and compareAndSet. All operations mutate the same reference in place.

Signature

interface MutableRef<out T> extends Pipeable, Inspectable {
  readonly "~effect/MutableRef": "~effect/MutableRef";
  current: T;
}

Mutations

compareAndSet

Added in v2.0.0 Source

Sets the value to newValue atomically if the current value equals oldValue. Returns true if the value was updated, false otherwise. Uses Effect's Equal interface for value comparison.

When to use

Use to replace a MutableRef value only when the current value still matches an expected value.

Signature

declare const compareAndSet: {
  <T>(oldValue: T, newValue: T): (self: MutableRef<T>) => boolean;
  <T>(self: MutableRef<T>, oldValue: T, newValue: T): boolean;
};

decrement

Added in v2.0.0 Source

Decrements a numeric MutableRef by 1 and returns the reference.

When to use

Use when you need an in-place MutableRef decrement that returns the same MutableRef.

Signature

declare function decrement(self: MutableRef<number>): MutableRef<number>;

decrementAndGet

Added in v2.0.0 Source

Decrements a numeric MutableRef by 1 and returns the new value.

When to use

Use to decrement a numeric MutableRef and immediately read the updated value.

Signature

declare function decrementAndGet(self: MutableRef<number>): number;

getAndDecrement

Added in v2.0.0 Source

Decrements a numeric MutableRef by 1 and returns the previous value.

When to use

Use to read the current numeric MutableRef value before decrementing it.

Signature

declare function getAndDecrement(self: MutableRef<number>): number;

getAndIncrement

Added in v2.0.0 Source

Increments a numeric MutableRef by 1 and returns the previous value.

When to use

Use to read the current numeric MutableRef value before incrementing it.

Signature

declare function getAndIncrement(self: MutableRef<number>): number;

getAndSet

Added in v2.0.0 Source

Sets the MutableRef to a new value and returns the previous value.

When to use

Use to replace the current MutableRef value while keeping the previous value.

Signature

declare const getAndSet: {
  <T>(value: T): (self: MutableRef<T>) => T;
  <T>(self: MutableRef<T>, value: T): T;
};

getAndUpdate

Added in v2.0.0 Source

Updates the MutableRef with the result of applying a function to its current value, and returns the previous value.

When to use

Use to transform the current MutableRef value while keeping the previous value.

Signature

declare const getAndUpdate: {
  <T>(f: (value: T) => T): (self: MutableRef<T>) => T;
  <T>(self: MutableRef<T>, f: (value: T) => T): T;
};

increment

Added in v2.0.0 Source

Increments a numeric MutableRef by 1 and returns the reference.

When to use

Use when you need an in-place MutableRef increment that returns the same MutableRef.

Signature

declare function increment(self: MutableRef<number>): MutableRef<number>;

incrementAndGet

Added in v2.0.0 Source

Increments a numeric MutableRef by 1 and returns the new value.

When to use

Use to increment a numeric MutableRef and immediately read the updated value.

Signature

declare function incrementAndGet(self: MutableRef<number>): number;

set

Added in v2.0.0 Source

Sets the MutableRef to a new value and returns the reference.

When to use

Use when you need an in-place MutableRef replacement that returns the same MutableRef.

Signature

declare const set: {
  <T>(value: T): (self: MutableRef<T>) => MutableRef<T>;
  <T>(self: MutableRef<T>, value: T): MutableRef<T>;
};

setAndGet

Added in v2.0.0 Source

Sets the MutableRef to a new value and returns the new value.

When to use

Use to replace the current MutableRef value and immediately read the replacement.

Signature

declare const setAndGet: {
  <T>(value: T): (self: MutableRef<T>) => T;
  <T>(self: MutableRef<T>, value: T): T;
};

toggle

Added in v2.0.0 Source

Switches a boolean MutableRef between true and false, then returns the reference.

When to use

Use when you need an in-place boolean MutableRef toggle that returns the same MutableRef.

Signature

declare function toggle(self: MutableRef<boolean>): MutableRef<boolean>;

update

Added in v2.0.0 Source

Updates the MutableRef with the result of applying a function to its current value, and returns the reference.

When to use

Use when you need an in-place MutableRef value transformation that returns the same MutableRef.

Signature

declare const update: {
  <T>(f: (value: T) => T): (self: MutableRef<T>) => MutableRef<T>;
  <T>(self: MutableRef<T>, f: (value: T) => T): MutableRef<T>;
};

updateAndGet

Added in v2.0.0 Source

Updates the MutableRef with the result of applying a function to its current value, and returns the new value.

When to use

Use to transform the current MutableRef value and immediately read the updated value.

Signature

declare const updateAndGet: {
  <T>(f: (value: T) => T): (self: MutableRef<T>) => T;
  <T>(self: MutableRef<T>, f: (value: T) => T): T;
};