feat: atomTree

[dmaskasky]

Summary

This pull request adds a new utility, atomTree, which allows us to manage hierarchical Jotai atoms in a tree-like structure. It works similarly to Jotai’s atomFamily but provides subtree management, making it convenient to remove or inspect entire branches.

import { atom } from 'jotai'
import { atomTree } from 'jotai-family'

const tree = atomTree((path) => atom(path.join('-')))

const atomA = tree(['foo', 'bar'])
const atomB = tree(['foo', 'bar'])

// Remove the atom at the given path
tree.remove(['foo', 'bar'])

Details

Creating Path Atoms

tree(path: Path): AtomType

Creates (or retrieves) an atom at the specified path. Subsequent calls with the same path return the same atom instance.

Removing Path Atoms

tree.remove(path: Path, removeSubTree = false): void

Removes the atom at the specified path. If removeSubTree is true, all child paths under that path are also removed.

This method removes the atom at the specified path. If removeSubTree is true, it also removes all child paths under that path.

Retrieving A Subtree

tree.getSubTree(path: Path): Node<AtomType> | undefined

Retrieves the internal node representing the specified path. This is useful for inspecting the tree structure. The node structure is as follows:

type Node<AtomType> = {
  atom?: AtomType
  children?: Map<PathSegment, Node<AtomType>>
}

Retrieving A Node Path

tree.getNodePath(path: Path): Node<AtomType>[]

Returns an array of node objects from the root node to the node at the specified path, inclusive.

Why we need this

• Managing data in a hierarchical structure is a common requirement in applications (e.g., file systems, nested comments, or deeply nested UI states).
• atomTree provides a convenient way to handle nested states, removing entire subtrees when they are no longer needed.

How it works

• Internally, atomTree maintains a root object of type Node, having a Map for children and an optional atom reference.
• Each path segment navigates deeper into the map, creating sub-nodes as needed.
• Removing subtrees cleans up child nodes and references to maintain a healthy and predictable state tree.

Please review and let me know if you have any suggestions or concerns. Thank you!

Credit: For the inspiration, thank you @paralin

[paralin]

@dmaskasky nice! 👍🏽

check out for context: https://github.com/paralin/jotai-tree-state-prototype/blob/master/src/jotai-persist.tsx

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[paralin]

Cool!