Options
All
  • Public
  • Public/Protected
  • All
Menu

@libre/atom

Index

Classes

Interfaces

Type aliases

Functions

Type aliases

AtomState

AtomState: AtomState<A>

Extracts the type info of an Atom's inner state

example

const state = Atom.of({count: 0});
const increment = (s: AtomState<typeof state>) => ({ count: s.count + 1 })
swap(state, increment);

DeepImmutable

DeepImmutable: T & T extends Primitive ? T : T extends (infer U)[] ? DeepImmutableArray<U> : T extends Map<infer K, infer V> ? DeepImmutableMap<K, V> : DeepImmutableObject<T>

A value or data structure which cannot be mutated

Functions

addChangeHandler

  • addChangeHandler<S>(atom: Atom<S>, key: string, handler: function): void

  • Registers a function to be run each time the state of atom changes.

    Will throw an Error if key is already taken by another handler.

    example
    
import {Atom, addChangeHandler, swap} from '@libre/atom'

const countAtom = Atom.of({ count: 0 })

addChangeHandler(countAtom, "log", ({current, previous}) => {
console.log(previous, current)
})

swap(countAtom, (state) => ({ count: state.count + 1 }))


// stdout logs:
// { count: 0 }
// { count: 1 }

    Type parameters

    • S

    Parameters

    • atom: Atom<S>
    • key: string
    • handler: function
        • (states: object): void

        • Parameters

          • states: object

          Returns void

    Returns void

deref

  • Dereferences (i.e. "reads") the current state of an Atom. The dereferenced value should not be mutated.

    example
    
import {Atom, deref} from '@libre/atom'

const stateAtom = Atom.of({ count: 0 })

deref(stateAtom) // => { count: 0 }

    Type parameters

    • S

      the type of atom's inner state

    Parameters

    Returns DeepImmutable<S>

getValidator

  • getValidator<S>(atom: Atom<S>): NonNullable<undefined | validator>

  • Gets atom's validator function

    example
    
import {Atom, deref, getValidator, swap} from '@libre/atom'

const atom = Atom.of({ count: 0 }, { validator: (state) => isEven(state.count) })
const validator = getValidator(atom)
validator({ count: 3 }) // => false
validator({ count: 2 }) // => true

    Type parameters

    • S

      the type of atom's inner state

    Parameters

    Returns NonNullable<undefined | validator>

removeChangeHandler

  • removeChangeHandler<S>(atom: Atom<S>, key: string): void

  • Deletes the key and the handler associated with key so that it not longer runs when the state of atom changes.

    example
    
import {Atom, addChangeHandler, removeChangeHandler, swap} from '@libre/atom'

const countAtom = Atom.of({ count: 0 })

addChangeHandler(countAtom, "log", ({current, previous}) => {
console.log(previous, current)
})

swap(countAtom, (state) => ({ count: state.count + 1 }))

// stdout logs:
// { count: 0 }
// { count: 1 }

removeChangeHandler(atom, "log")

swap(countAtom, (state) => ({ count: state.count + 1 }))

// nothing is logged

    Type parameters

    • S

    Parameters

    • atom: Atom<S>
    • key: string

    Returns void

set

  • set<S>(atom: Atom<S>, nextState: S): void

  • Sets atoms state to nextState.

    It is equivalent to swap(atom, () => newState).

    example
    
import {Atom, deref, set} from '@libre/atom'

const atom = Atom.of({ count: 0 })

set(atom, { count: 100 })
deref(atom) // => { count: 100 }

    Type parameters

    • S

      the type of atom's inner state

    Parameters

    • atom: Atom<S>

      an instance of Atom

    • nextState: S

      the value to which to set the state; it should be the same type/interface as current state

    Returns void

setValidator

  • setValidator<S>(atom: Atom<S>, validator: NonNullable<undefined | validator>): void

  • Sets the validator for atom. validator must be a pure function of one argument, which will be passed the intended new state on any state change. If the new state is unacceptable, validator should return false or throw an exception. If the current state is not acceptable to the new validator, an exception will be thrown and the validator will not be changed.

    example
    
import {Atom, deref, setValidator, set} from '@libre/atom'
import { _setValidator } from './internal-state';

const atom = Atom.of({ count: 0 }, {validator: (state) => isNumber(state.count) })
setValidator(atom, (state) => isOdd(state.count)) // Error; new validator rejected
set(atom, {count: "not number"}) // Error; new state not set
setValidator(atom, (state) => isEven(state.count)) // All good
set(atom, {count: 2}) // All good

    Type parameters

    • S

      the type of atom's inner state

    Parameters

    Returns void

swap

  • swap<S>(atom: Atom<S>, updateFn: function): void

  • Swaps atom's state with the value returned from applying updateFn to atom's current state. updateFn should be a pure function and not mutate state.

    example
    
import {Atom, swap} from '@libre/atom'
import {prettyPrint} from './prettyPrint'

const stateAtom = Atom.of({ count: 0 })
const increment = () => swap(stateAtom, (state) => ({
 count: state.count + 1
}));

    Type parameters

    • S

      the type of atom's inner state

    Parameters

    • atom: Atom<S>

      an instance of Atom

    • updateFn: function

      a pure function that takes the current state and returns the next state; the next state should be of the same type/interface as the current state;

        • (state: S): S

        • Parameters

          • state: S

          Returns S

    Returns void