SubscriptionRef

Stores mutable state and publishes changes as a stream.

A SubscriptionRef<A> stores the latest value, publishes the initial value, and publishes every committed update so subscribers can observe state over time. Updates are serialized so only one change is applied at a time. This module includes constructors, current-value reads, the changes stream, writes, updates, partial updates, and effectful update helpers.

26 exports Added in v2.0.0 Source

Constructors

make

Added in v2.0.0 Source

Constructs a new SubscriptionRef from an initial value.

When to use

Use to create a SubscriptionRef when consumers need to read the latest value and subscribe to every update.

Details

The initial value is published during construction, so changes starts new subscribers with that value before future updates.

See

changes for streaming the current value and subsequent updates
set for replacing the value and notifying subscribers

Signature

declare function make<A>(value: A): Effect<SubscriptionRef<A>>;

Getters

get

Added in v2.0.0 Source

Retrieves the current value of the SubscriptionRef.

Signature

declare function get<A>(self: SubscriptionRef<A>): Effect<A>;

getAndSet

Added in v2.0.0 Source

Retrieves the current value and sets a new value atomically, notifying subscribers of the change.

Signature

declare const getAndSet: {
  <A>(value: A): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, value: A): Effect<A>;
};

getAndUpdate

Added in v2.0.0 Source

Retrieves the current value and updates it atomically with the result of applying a function, notifying subscribers of the change.

Signature

declare const getAndUpdate: {
  <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect<A>;
};

getAndUpdateEffect

Added in v2.0.0 Source

Retrieves the current value and updates it atomically with the result of applying an effectful function, notifying subscribers of the change.

Signature

declare const getAndUpdateEffect: {
  <A, E, R>(update: (a: A) => Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect<A, E, R>;
  <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect<A, E, R>): Effect<A, E, R>;
};

getAndUpdateSome

Added in v2.0.0 Source

Retrieves the current value and optionally updates the reference.

When to use

Use to read the old SubscriptionRef value while applying a synchronous update only when a new value is available.

Details

If the function returns Option.some, the new value is set and published. If it returns Option.none, the reference is left unchanged and no update is published.

Signature

declare const getAndUpdateSome: {
  <A>(update: (a: A) => Option<A>): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => Option<A>): Effect<A>;
};

getAndUpdateSomeEffect

Added in v2.0.0 Source

Retrieves the current value and optionally updates the reference effectfully.

When to use

Use to read the old SubscriptionRef value while applying an effectful update only when a new value is available.

Details

If the effect succeeds with Option.some, the new value is set and published. If it succeeds with Option.none, the reference is left unchanged and no update is published.

Signature

declare const getAndUpdateSomeEffect: {
  <A, R, E>(
    update: (a: A) => Effect<Option<A>, E, R>,
  ): (self: SubscriptionRef<A>) => Effect<A, E, R>;
  <A, R, E>(self: SubscriptionRef<A>, update: (a: A) => Effect<Option<A>, E, R>): Effect<A, E, R>;
};

getUnsafe

Added in v4.0.0 Source

Retrieves the current value of the SubscriptionRef unsafely.

When to use

Use when you are in synchronous internals or test setup where concurrent updates are controlled.

Gotchas

This function directly accesses the underlying reference without any synchronization. It should only be used when you are certain there are no concurrent modifications.

Signature

declare function getUnsafe<A>(self: SubscriptionRef<A>): A;

Guards

isSubscriptionRef

Added in v4.0.0 Source

Returns true if the provided value is a SubscriptionRef.

When to use

Use to narrow an unknown value before calling SubscriptionRef operations that require a subscription reference.

Signature

declare const isSubscriptionRef: (u: unknown) => u is SubscriptionRef<unknown>;

Models

SubscriptionRef interface

Added in v2.0.0 Source

A mutable reference whose updates are serialized and published to subscribers.

When to use

Use to observe the current value and subsequent updates as a stream.

Signature

interface SubscriptionRef<in out A> extends Variance<A>, Pipeable {
  readonly pubsub: PubSub<A>;
  readonly semaphore: Semaphore;
  value: A;
}

Mutations

modify

Added in v2.0.0 Source

Modifies the SubscriptionRef atomically with a function that computes a return value and a new value, notifying subscribers of the change.

Signature

declare const modify: {
  <A, B>(modify: (a: A) => readonly [B, A]): (self: SubscriptionRef<A>) => Effect<B>;
  <A, B>(self: SubscriptionRef<A>, f: (a: A) => readonly [B, A]): Effect<B>;
};

modifyEffect

Added in v2.0.0 Source

Modifies the SubscriptionRef atomically with an effectful function that computes a return value and a new value, notifying subscribers of the change.

Signature

declare const modifyEffect: {
  <B, A, E, R>(
    modify: (a: A) => Effect<readonly [B, A], E, R>,
  ): (self: SubscriptionRef<A>) => Effect<B, E, R>;
  <A, B, E, R>(
    self: SubscriptionRef<A>,
    modify: (a: A) => Effect<readonly [B, A], E, R>,
  ): Effect<B, E, R>;
};

modifySome

Added in v2.0.0 Source

Computes a return value and optionally updates the reference.

When to use

Use to return a separate result while synchronously deciding whether to publish a new SubscriptionRef value.

Details

If the function returns Option.some for the new value, the value is set and published. If it returns Option.none, the reference is left unchanged and no update is published.

Signature

declare const modifySome: {
  <B, A>(modify: (a: A) => readonly [B, Option<A>]): (self: SubscriptionRef<A>) => Effect<B>;
  <A, B>(self: SubscriptionRef<A>, modify: (a: A) => readonly [B, Option<A>]): Effect<B>;
};

modifySomeEffect

Added in v2.0.0 Source

Computes a return value and optionally updates the reference effectfully.

When to use

Use to return a separate result while effectfully deciding whether to publish a new SubscriptionRef value.

Details

If the effect succeeds with Option.some, the new value is set and published. If it succeeds with Option.none, the reference is left unchanged and no update is published.

Signature

declare const modifySomeEffect: {
  <A, B, R, E>(
    modify: (a: A) => Effect<readonly [B, Option<A>], E, R>,
  ): (self: SubscriptionRef<A>) => Effect<B, E, R>;
  <A, B, R, E>(
    self: SubscriptionRef<A>,
    modify: (a: A) => Effect<readonly [B, Option<A>], E, R>,
  ): Effect<B, E, R>;
};

set

Added in v2.0.0 Source

Sets the value of the SubscriptionRef, notifying all subscribers of the change.

Signature

declare const set: {
  <A>(value: A): (self: SubscriptionRef<A>) => Effect<void>;
  <A>(self: SubscriptionRef<A>, value: A): Effect<void>;
};

setAndGet

Added in v2.0.0 Source

Sets the value of the SubscriptionRef and returns the new value, notifying all subscribers of the change.

Signature

declare const setAndGet: {
  <A>(value: A): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, value: A): Effect<A>;
};

update

Added in v2.0.0 Source

Updates the value of the SubscriptionRef with the result of applying a function, notifying subscribers of the change.

Signature

declare const update: {
  <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect<void>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect<void>;
};

updateAndGet

Added in v2.0.0 Source

Updates the value of the SubscriptionRef with the result of applying a function and returns the new value, notifying subscribers of the change.

Signature

declare const updateAndGet: {
  <A>(update: (a: A) => A): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => A): Effect<A>;
};

updateAndGetEffect

Added in v2.0.0 Source

Updates the value of the SubscriptionRef with the result of applying an effectful function and returns the new value, notifying subscribers of the change.

Signature

declare const updateAndGetEffect: {
  <A, E, R>(update: (a: A) => Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect<A, E, R>;
  <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect<A, E, R>): Effect<A, E, R>;
};

updateEffect

Added in v2.0.0 Source

Updates the value of the SubscriptionRef with the result of applying an effectful function, notifying subscribers of the change.

Signature

declare const updateEffect: {
  <A, E, R>(update: (a: A) => Effect<A, E, R>): (self: SubscriptionRef<A>) => Effect<void, E, R>;
  <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect<A, E, R>): Effect<void, E, R>;
};

updateSome

Added in v2.0.0 Source

Applies an update function to the current value. If it returns Option.some, sets and publishes that value; if it returns Option.none, leaves the reference unchanged and does not publish.

Signature

declare const updateSome: {
  <A>(update: (a: A) => Option<A>): (self: SubscriptionRef<A>) => Effect<void>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => Option<A>): Effect<void>;
};

updateSomeAndGet

Added in v2.0.0 Source

Applies an optional update and returns the current value afterward.

When to use

Use to conditionally update a SubscriptionRef and read the value that is current after the update decision.

Details

If the function returns Option.some, the new value is set, published, and returned. If it returns Option.none, the unchanged current value is returned without publishing.

Signature

declare const updateSomeAndGet: {
  <A>(update: (a: A) => Option<A>): (self: SubscriptionRef<A>) => Effect<A>;
  <A>(self: SubscriptionRef<A>, update: (a: A) => Option<A>): Effect<A>;
};

updateSomeAndGetEffect

Added in v2.0.0 Source

Applies an effectful optional update and returns the current value afterward.

When to use

Use to conditionally update a SubscriptionRef effectfully and read the value that is current after the update decision.

Details

If the effect succeeds with Option.some, the new value is set, published, and returned. If it succeeds with Option.none, the unchanged current value is returned without publishing.

Signature

declare const updateSomeAndGetEffect: {
  <A, E, R>(
    update: (a: A) => Effect<Option<A>, E, R>,
  ): (self: SubscriptionRef<A>) => Effect<A, E, R>;
  <A, E, R>(self: SubscriptionRef<A>, update: (a: A) => Effect<Option<A>, E, R>): Effect<A, E, R>;
};

updateSomeEffect

Added in v2.0.0 Source

Applies an effectful update only when it produces a new value.

When to use

Use to conditionally update a SubscriptionRef with an effectful function while discarding the resulting value.

Details

If the effect succeeds with Option.some, the new value is set and published. If it succeeds with Option.none, the reference is left unchanged and no update is published.

Signature

declare const updateSomeEffect: {
  <A, E, R>(
    update: (a: A) => Effect<Option<A>, E, R>,
  ): (self: SubscriptionRef<A>) => Effect<void, E, R>;
  <A, E, R>(
    self: SubscriptionRef<A>,
    update: (a: A) => Effect<Option<A>, E, R>,
  ): Effect<void, E, R>;
};

Details

The stream will first emit the current value, then emit all future changes as they occur.

Signature

declare function changes<A>(self: SubscriptionRef<A>): Stream<A>;