included in @reatom/framework

All atoms and actions have a hooks to they lifecycle, this package exposes friendly helpers to use this hooks.

We assumes that you already read lifecycle guide.

A lot of cool examples you could find in async package docs.

onConnect

onConnect allows you to react to atom connection (first subscribtion). Optionally, you could return a cleanup callback.

All connection (and disconnection) callbacks calling during effects queue - outside batching. The returned value is a dispose function used to deactivate the hook.

"Connection" refers to the presence of any number of subscribers in the atom. The first subscriber activates the connection status, while the second subscriber does not interact with it. Unsubscribing the first subscriber has no effect since there is still one subscriber (the second one). However, after unsubscribing the second subscriber, the connection status will be deactivated, all related ctx.schedule will throws AbortError and if a cleanup callback is provided, it will be triggered. You can read more in the lifecycle guide.

import { atom } from '@reatom/core'
import { onConnect } from '@reatom/hooks'

export const messagesAtom = atom([], 'messagesAtom')
const dispose = onConnect(messagesAtom, (ctx) => {
  const cb = (message) => {
    messagesAtom(ctx, (messages) => [...messages, message])
  }

  WS.on('message', cb)

  return () => WS.off('message', cb)
})

Since connection context follow Reatom concurrent abort strategy, you can use any infinity effects with a leaks safety. In the example above the loop will not stack forever, if the atom will disconnected, as the schedule method will throw an abort error in this case.

// lazy retry logic
onConnect(fetchSome.dataAtom, async (ctx) => {
  while (true) {
    await ctx.schedule(() => sleep(5_000))
    await fetchSome(ctx)
  }
})

Deprecated! The passed ctx has an isConnected method to check the current status of the passed atom. You can refer to the async example for more information. Additionally, the ctx includes a controller property, which is an AbortController. You can conveniently reuse it with reatomAsync. For further details, you can refer to another async example.

Comparison with React

For example, in React you should manage abort strategy by yourself by useEffect, if you want to cancel async process on unmount.

import { reatomAsync, withAbort, withDataAtom } from '@reatom/async'
import { useAtom, useAction } from '@reatom/npm-react'

export const fetchList = reatomAsync((ctx) => request('api/list', ctx.controller), 'fetchList').pipe(
  withAbort(),
  withDataAtom([]),
)

export const List = () => {
  const [list] = useAtom(fetchList.dataAtom)
  const handleFetch = useAction(fetchList)
  const handleAbort = useAction(fetchList.abort)

  useEffect(() => {
    handleFetch()
    return handleAbort
  }, [])

  return <ul>{list.map(() => '...')}</ul>
}

With Reatom, you can simplify it and make it more readable.

import { reatomAsync, onConnect, withDataAtom } from '@reatom/framework'
import { useAtom } from '@reatom/npm-react'

export const fetchList = reatomAsync((ctx) => request('api/list', ctx.controller), 'fetchList').pipe(withDataAtom([]))
onConnect(fetchList.dataAtom, fetchList)

export const List = () => {
  const [list] = useAtom(fetchList.dataAtom)

  return <ul>{list.map(() => '...')}</ul>
}

Isn't it cool, how the size of the code is reduced and how the logic is simplified?

onDisconnect

Shortcut to onConnect returned callback.

withInit

This operator helps you to initialize the state lazily on the first atom read.

import { atom } from '@reatom/core'
import { withInit } from '@reatom/hooks'

export const langAtom = atom('', 'langAtom').pipe(
  withInit(() => navigator.languages?.[0] ?? (navigator.language || navigator.userLanguage)),
)

You can use it to depend the init state from an other atom too.

import { atom } from '@reatom/core'
import { withInit } from '@reatom/hooks'

export const pageTitleAtom = atom('', 'pageTitleAtom')

export const searchAtom = atom('', 'searchAtom').pipe(withInit((ctx) => ctx.get(pageTitleAtom)))

Also, you can use it to do a side effects in rare cases.

export const pageUptimeAtom = atom(0, 'pageUptimeAtom').pipe(
  withInit((ctx) => {
    setTimeout(() => pageUptimeAtom(ctx, performance.now()), 1000)
    return performance.now()
  }),
)

export const dataAtom = atom(0, 'dataAtom').pipe(
  withInit((ctx, init) => {
    ctx.get(socketServiceAtom).on('data', (data) => dataAtom(ctx, data))

    return init(ctx)
  }),
)

Note that the subscription will leave forever. To manage resources more efficiently, you can use should use probably onConnect.

isInit

This utility allows you to check that the current atom or action is being called for the first time (in the current context). It is useful to perform some initialisation effects only once.

import { action } from '@reatom/core'
import { isInit } from '@reatom/hooks'

export const doSome = action((ctx, payload) => {
  if (isInit(ctx)) {
    // setup
  }
  return work()
})

onUpdate

The onUpdate hook allows you to react to state updates of the passed atom. However, this hook will be deprecated in the future. It is recommended and more convenient to use the atom's onChange method and the action's onCall method. You can find more information about these methods in the core package documentation.

For general computed atoms (via ctx.spy), it is only called when the atom is connected. You can read more in the lifecycle guide.

One unique feature of onUpdate is that it could activate the entire chain of dependent atoms if they are LensAtom or LensAction from the lens package. It useful when you want to delay or sample the reaction.

import { onUpdate } from '@reatom/hooks'
import { debounce } from '@reatom/lens'

onUpdate(onChange.pipe(debounce(250)), (ctx) => fetchData(ctx))