Skip to main content

gentleduck state

Experimental

Lightweight atomic state management for React with primitive and derived atoms.

Philosophy

@gentleduck/state keeps state modeling explicit with an atom/store API. It is optimized for predictable dependency tracking and small runtime surface area.

Installation

npm install @gentleduck/state
npm install @gentleduck/state

Usage

Core (vanilla)

import { atom, createStore } from '@gentleduck/state'
 
const count = atom(0)
const double = atom((get) => get(count) * 2)
 
const store = createStore()
store.set(count, (prev) => prev + 1)
console.log(store.get(double))
import { atom, createStore } from '@gentleduck/state'
 
const count = atom(0)
const double = atom((get) => get(count) * 2)
 
const store = createStore()
store.set(count, (prev) => prev + 1)
console.log(store.get(double))

React

import { atom } from '@gentleduck/state'
import { useAtom, useAtomValue, useSetAtom, Provider } from '@gentleduck/state/react'
 
const count = atom(0)
 
function Counter() {
  const [value, setValue] = useAtom(count)
  return <button onClick={() => setValue((c) => c + 1)}>{value}</button>
}
 
function App() {
  return (
    <Provider>
      <Counter />
    </Provider>
  )
}
import { atom } from '@gentleduck/state'
import { useAtom, useAtomValue, useSetAtom, Provider } from '@gentleduck/state/react'
 
const count = atom(0)
 
function Counter() {
  const [value, setValue] = useAtom(count)
  return <button onClick={() => setValue((c) => c + 1)}>{value}</button>
}
 
function App() {
  return (
    <Provider>
      <Counter />
    </Provider>
  )
}

API Reference

atom(initialValue)

Creates a primitive writable atom.

atom(read)

Creates a derived read-only atom. The read function receives a get accessor to read other atoms. Values are cached and only recomputed when dependencies change.

atom(read, write)

Creates a writable derived atom.

createStore()

Creates a store instance with:

  • get(atom) - read the current value of an atom
  • set(atom, valueOrUpdater) - update an atom's value (uses shallow equality to skip unnecessary notifications)
  • subscribe(atom, callback) - subscribe to changes, returns an unsubscribe function

React Hooks

useAtom(atom)

Returns a [value, setValue] tuple for writable atoms.

useAtomValue(atom)

Returns the current value of any atom (read-only or writable).

useSetAtom(atom)

Returns a setter function for writable atoms without subscribing to value changes.

Provider

Injects a store instance into the React tree. Components use the nearest Provider's store, or fall back to a global singleton.