feat(utils): Add loadable

src/utils.ts

@@ -19,3 +19,4 @@ export {
 } from './utils/atomWithStorage'
 export { atomWithObservable } from './utils/atomWithObservable'
 export { useHydrateAtoms } from './utils/useHydrateAtoms'
+export { loadable } from './utils/loadable'

src/utils/loadable.ts

@@ -0,0 +1,52 @@
+import { atom } from 'jotai'
+import type { Atom } from 'jotai'
+
+const loadableAtomCache = new WeakMap<Atom<unknown>, Atom<Loadable<any>>>()
+const errorLoadableCache = new WeakMap<object, Loadable<never>>()
+
+type Loadable<Value> =
+  | { state: 'loading' }
+  | { state: 'hasError'; error: unknown }
+  | { state: 'hasData'; data: Value }
+
+const LOADING_LOADABLE: Loadable<never> = { state: 'loading' }
+
+export function loadable<Value>(anAtom: Atom<Value>): Atom<Loadable<Value>> {
+  const cachedAtom = loadableAtomCache.get(anAtom)
+  if (cachedAtom) {
+    return cachedAtom
+  }
+
+  const derivedAtom = atom((get): Loadable<Value> => {
+    try {
+      const value = get(anAtom)
+
+      return {
+        state: 'hasData',
+        data: value,
+      }
+    } catch (error) {
+      if (error instanceof Promise) {
+        return LOADING_LOADABLE
+      }
+
+      const cachedErrorLoadable = errorLoadableCache.get(error as Error)
+
+      if (cachedErrorLoadable) {
+        return cachedErrorLoadable
+      }
+
+      const errorLoadable: Loadable<never> = {
+        state: 'hasError',
+        error,
+      }
+
+      errorLoadableCache.set(error as Error, errorLoadable)
+      return errorLoadable
+    }
+  })
+
+  loadableAtomCache.set(anAtom, derivedAtom)
+
+  return derivedAtom
+}

tests/utils/loadable.test.tsx

@@ -0,0 +1,149 @@
+import { fireEvent, render } from '@testing-library/react'
+import { Atom, atom } from '../../src/index'
+import { loadable, useAtomValue, useUpdateAtom } from '../../src/utils'
+import { getTestProvider } from '../testUtils'
+
+const Provider = getTestProvider()
+
+it('loadable turns suspense into values', async () => {
+  let resolveAsync!: (x: number) => void
+  const asyncAtom = atom(() => {
+    return new Promise<number>((resolve) => (resolveAsync = resolve))
+  })
+
+  const { findByText, getByText } = render(
+    <Provider>
+      <LoadableComponent asyncAtom={asyncAtom} />
+    </Provider>
+  )
+
+  getByText('Loading...')
+  resolveAsync(5)
+  await findByText('Data: 5')
+})
+
+it('loadable turns errors into values', async () => {
+  let rejectAsync!: (error: Error) => void
+  const asyncAtom = atom(() => {
+    return new Promise<number>((resolve, reject) => (rejectAsync = reject))
+  })
+
+  const { findByText, getByText } = render(
+    <Provider>
+      <LoadableComponent asyncAtom={asyncAtom} />
+    </Provider>
+  )
+
+  getByText('Loading...')
+  rejectAsync(new Error('An error occurred'))
+  await findByText('Error: An error occurred')
+})
+
+it('loadable turns primitive throws into values', async () => {
+  let rejectAsync!: (errorMessage: string) => void
+  const asyncAtom = atom(() => {
+    return new Promise<number>((resolve, reject) => (rejectAsync = reject))
+  })
+
+  const { findByText, getByText } = render(
+    <Provider>
+      <LoadableComponent asyncAtom={asyncAtom} />
+    </Provider>
+  )
+
+  getByText('Loading...')
+  rejectAsync('An error occurred')
+  await findByText('Error: An error occurred')
+})
+
+it('loadable goes back to loading after re-fetch', async () => {
+  let resolveAsync!: (x: number) => void
+  const refreshAtom = atom(0)
+  const asyncAtom = atom((get) => {
+    get(refreshAtom)
+    return new Promise<number>((resolve) => (resolveAsync = resolve))
+  })
+
+  const Refresh = () => {
+    const setRefresh = useUpdateAtom(refreshAtom)
+    return (
+      <>
+        <button onClick={() => setRefresh((value) => value + 1)}>
+          refresh
+        </button>
+      </>
+    )
+  }
+
+  const { findByText, getByText } = render(
+    <Provider>
+      <Refresh />
+      <LoadableComponent asyncAtom={asyncAtom} />
+    </Provider>
+  )
+
+  getByText('Loading...')
+  resolveAsync(5)
+  await findByText('Data: 5')
+  fireEvent.click(getByText('refresh'))
+  await findByText('Loading...')
+  resolveAsync(6)
+  await findByText('Data: 6')
+})
+
+it('loadable can recover from error', async () => {
+  let resolveAsync!: (x: number) => void
+  let rejectAsync!: (error: Error) => void
+  const refreshAtom = atom(0)
+  const asyncAtom = atom((get) => {
+    get(refreshAtom)
+    return new Promise<number>((resolve, reject) => {
+      resolveAsync = resolve
+      rejectAsync = reject
+    })
+  })
+
+  const Refresh = () => {
+    const setRefresh = useUpdateAtom(refreshAtom)
+    return (
+      <>
+        <button onClick={() => setRefresh((value) => value + 1)}>
+          refresh
+        </button>
+      </>
+    )
+  }
+
+  const { findByText, getByText } = render(
+    <Provider>
+      <Refresh />
+      <LoadableComponent asyncAtom={asyncAtom} />
+    </Provider>
+  )
+
+  getByText('Loading...')
+  rejectAsync(new Error('An error occurred'))
+  await findByText('Error: An error occurred')
+  fireEvent.click(getByText('refresh'))
+  await findByText('Loading...')
+  resolveAsync(6)
+  await findByText('Data: 6')
+})
+
+interface LoadableComponentProps {
+  asyncAtom: Atom<number | string>
+}
+
+const LoadableComponent = ({ asyncAtom }: LoadableComponentProps) => {
+  const value = useAtomValue(loadable(asyncAtom))
+
+  if (value.state === 'loading') {
+    return <>Loading...</>
+  }
+
+  if (value.state === 'hasError') {
+    return <>{String(value.error)}</>
+  }
+
+  return <>Data: {value.data}</>
+}