Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Atom<T>

Atom is the most basic unit of state. It contains a single value that can be set or updated in many places and these changes can be subscribed to allowing your application to be reactive. There are two ways to update an atoms value, you can either set it or udpate it. Setting the atom's value will clear all future updates and replace the value immediately, notifying subscribers. If you opt to update the value instead then your update function (or value) will be applied after all previous updates have been applied. This is useful if each new state value builds on the previous state value and ensures that each update is firing with the latest value as it's argument.

Example

 
const counter = atom(0);

const countDisplay = document.querySelector('#count-display');
counter.subscribe(atom => {
  countDisplay.textContent = `Current count: ${atom.value}`;
});

const incrementButton = document.querySelector('#increment-button');
incrementButton.addEventListener('click', () => counter.update(n => n + 1));
internal

DO NOT USE Prefer the atom factory function to manually creating instances of this class.

Type parameters

  • T

    The type of the atom's value.

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

  • new Atom<T>(value: T): Atom<T>

  • Creates a new Atom with an initial value.

    Type parameters

    • T

    Parameters

    • value: T

      The intitial value of the atom.

    Returns Atom<T>

Properties

Private #subscribers

#subscribers: AtomSubscriber<Atom<T>>[]

The list of active subscribers listening or value changes on this atom. Subscribers are called anytime the value is updated.

typeparam

The specific class that was subscribed to.

Private #updateTimeout

#updateTimeout: undefined | Timeout

P The update timeout, this is tracked since setting an atom's value will clear future updates so must cancel the asynchronous update timer.

Private #updaterQueue

#updaterQueue: AtomUpdateFunction<T>[]

The updater queue used to keep track of the order and amount of requested updates to the atom's current value.

Private #value

#value: T

The value of the atom, BaseAtom does not provide any means for updating this after the object is created.

typeparam

Teh atom's value.

Accessors

value

  • get value(): T

  • This readonly property will return the current active value of the atom.

    Returns T

    The current value of the atom.

Methods

Protected clearUpdateQueue

  • clearUpdateQueue(): void

  • Clears the update queue, emptying it out as well as clearing an update timeout if once is currently pending execution.

    Returns void

Protected hasSubscribers

  • hasSubscribers(): boolean

  • An internal test that determines if any subscribers are currently subscribed to this atom's value changes.

    Returns boolean

    A boolean representing if there are any subscribers currently subscribed to this atom.

Protected notifySubscribers

  • notifySubscribers(): void

  • An internal helper that will fire all the subscribers passing this to them, this is typically only triggered in response to value changes.

    Returns void

Protected queueUpdate

  • This method is a helper for update and is responsible for actually putting the update function into the queue. It also determines if needs to initiate an update timer. The update timer is only active when there are pending updates so it's possible we need to kick off the update timer in cases where we're updating the value after a period of no updates.

    Parameters

    • updater: AtomUpdateFunction<T>

      The update function that should be added to the pending update queue.

    Returns void

Protected runUpdate

  • runUpdate(): void

  • This method is a helper and is what is forward to setTimeout to handle dequeing the latest update and executing it. This method will also clear the update timer so that it's always unset when there is no timer running. Once the update is applied it will then reset the timeout if there are still updates remaining in the queue otherwise it ends without restarting a timer.

    Returns void

set

  • set(value: T): void

  • Set, much like update, will modify the value of the atom. The core difference between set and update though is that set is immediate and will clear any future updates. If you think of the counter example you would prefer to use update to add or subtract from the current value; but, you would want to use set in the case of resetting it's value back to 0 as it would be immediate and also cancel any pending updates. Set does still notify subscribers that the value has changed.

    Parameters

    • value: T

      The new value of the atom that should be set immediately.

    Returns void

Protected setValue

  • setValue(newValue: T): void

  • An internal helper that will update the value of the atom. Note that it's protected, there is no public way to modify a BaseAtom's value this is for subclasses to used.

    Parameters

    • newValue: T

      The new value for the atom's value field.

    Returns void

subscribe

  • subscribe(subscriber: AtomSubscriber<Atom<T>>): void

  • Subscribe to the atom's value updates with the given subscriber. This subscriber will be called with the instance of the atom anytime it's value changes (of course the BaseAtom does not have a public mechanism for the value to change).

    Parameters

    • subscriber: AtomSubscriber<Atom<T>>

      The subscriber to add to the list of subscribers listening for value changes.

    Returns void

unsubscribe

  • unsubscribe(subscriber: null | AtomSubscriber<Atom<T>>): void

  • Unsubscribe the given subscriber from value updates on this atom. If the subscriber is in the list of subscribers it will be removed, and if it's no already a subscriber then nothing will happen. If null is passed instead of a subscriber then all subscribers will be removed.

    Parameters

    • subscriber: null | AtomSubscriber<Atom<T>>

      The subscriber to remove or null to remove all subscribers.

    Returns void

update

  • Queue and update for the atom's value. There is no guarantee that when this is called the value will be udpdated immediately, the update is queued and set up to be called in order with other updates. After each update the atom will notify subscribers the value has changed.

    Parameters

    • updater: AtomUpdater<T>

      The new value, or update function, that will be called when this update's place in the queue is reached.

    Returns void

Generated using TypeDoc