feat: add atom

Author: robertherber

src/utils/atom.md

@@ -0,0 +1,55 @@
+# Atom
+
+Atom is the root primitive that is missing in React (could be extended for others). It is a simple object that holds a value and can be set and read independently of the React lifecycle:
+- It makes it easy to hold a singleton state (for example auth token)
+- It makes it easy to hold a state that is not related to the component lifecycle (for example background jobs in React Native)
+- It can potentially sync state with other frameworks than React
+- It integrates fully with the React lifecycle, as one would expect, but you can also use it without triggering a re-render (by using `.get()` or `.value`)
+
+## createAtom
+
+The base for everything is create atom. This holds a value and can be read and set.
+
+```typescript
+const atom = createAtom(5)
+
+console.log(atom.value) // 5
+atom.set(6)
+console.log(atom.value) // 6
+```
+## .set()
+Similarly to setState you can supply a callback to the set method. This callback will receive the current value and should return the new value, which results in an atomic update
+```typescript
+atom.set(v => v + 1)
+```
+
+## .get()
+You can read the value of the atom using the `.get()` method or by accessing the `.value` property
+```typescript
+console.log(atom.get()) // 7
+console.log(atom.value) // 7
+```
+
+## useAtom
+
+The `useAtom` hook is the main way to interact with atoms in a React component or custom hook. It returns the current value. The component will re-render when the value changes. 
+
+We considered returning the same signature as `useState` for familiarity but decided against it. The `.set()` function does not care whether it's executed in a React context or not, so it wouldn't add any value.
+
+```typescript
+function MyComponent() {
+  const value = useAtom(atom)
+  const increment = () => atom.set(v => v + 1)
+
+  return <div onClick={increment}>{value}</div>
+}
+```
+
+## Persisting atoms
+
+You can persist atoms using the `persistAtom` function. This will store the atom in localStorage and rehydrate it on page load. It takes the atom, a key and any compatible storage (localStorage, sessionStorage or AsyncStorage). It basically accepts any key value store that has a `getItem` and `setItem` method. By default it will persist the atom every 100ms, but you can pass any debounce time in milliseconds as the third argument.
+
+```typescript
+const atom = createAtom(5)
+persistAtom(atom, 'my-atom-key', localStorage)
+```

src/utils/atom.test.ts

@@ -0,0 +1,147 @@
+import { renderHook, act } from '@testing-library/react-hooks'
+
+import {
+  AtomAsyncStorage,
+  AtomStorage, createAtom, persistAtom, useAtom,
+} from './atom'
+
+describe('createAtom', () => {
+  test('get initial value', () => {
+    const counter = createAtom(1)
+
+    expect(counter.get()).toBe(1)
+  })
+
+  test('set value', () => {
+    const counter = createAtom(1)
+
+    counter.set(2)
+
+    expect(counter.get()).toBe(2)
+  })
+
+  test('set value with setter', () => {
+    const counter = createAtom(1)
+
+    counter.set((val) => val + 1)
+
+    expect(counter.get()).toBe(2)
+  })
+})
+
+describe('persistence', () => {
+  test('should read null store', () => {
+    const storage: AtomStorage = {
+      getItem: jest.fn(),
+      setItem: jest.fn(),
+    }
+    const counter = createAtom(1)
+    const val = persistAtom(counter, 'counter', storage)
+
+    expect(val).toBe(null)
+    expect(counter.value).toBe(1)
+
+    expect(storage.getItem).toHaveBeenCalledWith('counter')
+    expect(storage.getItem).toHaveBeenCalledTimes(1)
+  })
+
+  test('should await null store', async () => {
+    const storage: AtomAsyncStorage = {
+      getItem: jest.fn(async () => Promise.resolve('3')),
+      setItem: jest.fn(),
+    }
+    const counter = createAtom(1)
+    const val = await persistAtom(counter, 'counter', storage)
+
+    expect(val).toBe(3)
+    expect(counter.value).toBe(3)
+
+    expect(storage.getItem).toHaveBeenCalledWith('counter')
+    expect(storage.getItem).toHaveBeenCalledTimes(1)
+  })
+
+  test('should read store with value', () => {
+    const storage: AtomStorage = {
+      getItem: jest.fn(() => '2'),
+      setItem: jest.fn(),
+    }
+    const counter = createAtom(1)
+    const val = persistAtom(counter, 'counter', storage)
+
+    expect(val).toBe(2)
+    expect(counter.value).toBe(2)
+
+    expect(storage.getItem).toHaveBeenCalledWith('counter')
+    expect(storage.getItem).toHaveBeenCalledTimes(1)
+  })
+
+  test('should write store with value', () => {
+    jest.useFakeTimers()
+    const storage: AtomStorage = {
+      getItem: jest.fn(() => '2'),
+      setItem: jest.fn(),
+    }
+    const counter = createAtom(1)
+    persistAtom(counter, 'counter', storage)
+
+    counter.set(3)
+
+    jest.runAllTimers()
+
+    expect(storage.setItem).toHaveBeenCalledWith('counter', '3')
+    expect(storage.setItem).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('listener', () => {
+  test('addListener', () => {
+    const counter = createAtom(1)
+
+    const spy = jest.fn()
+    counter.addListener(spy)
+
+    counter.set((val) => val + 1)
+
+    expect(spy).toHaveBeenCalledWith(2, 1)
+  })
+
+  test('remove listener', () => {
+    const counter = createAtom(1)
+
+    const spy = jest.fn()
+    const { remove } = counter.addListener(spy)
+
+    counter.set((val) => val + 1)
+
+    remove()
+
+    counter.set((val) => val + 1)
+
+    expect(spy).toHaveBeenCalledWith(2, 1)
+    expect(spy).not.toHaveBeenCalledWith(3, 2)
+  })
+})
+
+describe('useAtom', () => {
+  test('initial value', () => {
+    const counter = createAtom(1)
+
+    const { result } = renderHook(() => useAtom(counter))
+
+    expect(result.current).toBe(1)
+  })
+
+  test('increment value', () => {
+    const counter = createAtom(1)
+
+    const { result } = renderHook(() => useAtom(counter))
+
+    expect(result.current).toBe(1)
+
+    act(() => {
+      counter.set((val) => val + 1)
+    })
+
+    expect(result.current).toBe(2)
+  })
+})

src/utils/atom.ts

@@ -0,0 +1,134 @@
+/* eslint-disable functional/immutable-data */
+import { useState, useEffect } from 'react'
+
+type JSONValue =
+    | string
+    | number
+    | boolean
+    | JSONObject
+    | JSONArray;
+
+interface JSONObject {
+  readonly [x: string]: JSONValue;
+}
+
+type ToPrimitive<T> =
+  T extends string ? string
+    : T extends number ? number
+      : T extends boolean ? boolean
+        : T;
+
+export type AtomStorage = {
+  readonly setItem: (key: string, value: string) => void,
+  readonly getItem: (key: string) => string | null
+}
+
+export type AtomAsyncStorage = {
+  readonly setItem: (key: string, value: string) => Promise<void>,
+  readonly getItem: (key: string) => Promise<string | null>
+}
+
+interface JSONArray extends Array<JSONValue> { }
+
+export class Atom<T extends JSONValue> {
+  /* eslint-disable functional/prefer-readonly-type */
+  #value: T
+
+  /* eslint-disable functional/prefer-readonly-type */
+  #subscribers: readonly ((newVal: T, prevVal: T) => void)[]
+
+  constructor(initialValue: T) {
+    this.#value = initialValue
+    this.#subscribers = []
+  }
+
+  get value() {
+    return this.#value
+  }
+
+  get() {
+    return this.#value
+  }
+
+  addListener(cb: (newVal: T, prevVal: T) => void) {
+    this.#subscribers = [...this.#subscribers, cb]
+    const remove = () => {
+      this.#subscribers = this.#subscribers.filter((fn) => fn !== cb)
+    }
+    return { remove }
+  }
+
+  set(value: (T | ((val: T) => T))) {
+    const prevValue = this.#value
+    this.#value = typeof value === 'function' ? value(this.#value) : value
+    if (this.#value !== prevValue) {
+      this.#subscribers.forEach((sub) => {
+        sub(this.#value, prevValue)
+      })
+    }
+  }
+}
+
+export function createAtom<T extends JSONValue>(initialValue: ToPrimitive<T>) {
+  return new Atom<ToPrimitive<T>>(initialValue)
+}
+
+export function useAtom<T extends JSONValue>(atom: Atom<T>) {
+  const [val, setVal] = useState<T>(atom.value)
+
+  useEffect(() => {
+    const { remove } = atom.addListener((newVal) => {
+      setVal(newVal)
+    })
+    return remove
+  }, [atom])
+
+  return val
+}
+
+const debounce = (fn: () => void, delay: number) => {
+  let timeoutId: ReturnType<typeof setTimeout>
+  return () => {
+    clearTimeout(timeoutId)
+    timeoutId = setTimeout(fn, delay)
+  }
+}
+
+export function persistAtom<T extends JSONValue, TStorage extends AtomStorage | AtomAsyncStorage>(
+  atom: Atom<T>,
+  key: string,
+  Storage: TStorage,
+  opts?: { readonly debounce?: number },
+): TStorage extends AtomAsyncStorage ? Promise<T | null> : T | null {
+  const valueOrPromise = Storage.getItem(key)
+
+  const startSubscribing = () => {
+    atom.addListener(debounce(() => {
+      void Storage.setItem(key, JSON.stringify(atom.value))
+    }, opts?.debounce ?? 100))
+  }
+
+  const handleValue = (value: string | null) => {
+    if (value) {
+      const valueAsJSON = JSON.parse(value) as T
+
+      atom.set(valueAsJSON)
+
+      startSubscribing()
+
+      return valueAsJSON as T
+    }
+
+    startSubscribing()
+
+    return null
+  }
+
+  if (valueOrPromise instanceof Promise) {
+    // @ts-expect-error contained
+    return valueOrPromise.then(handleValue)
+  }
+
+  // @ts-expect-error contained
+  return handleValue(valueOrPromise)
+}