docs: document atom factory for v2

Omnistac · bowheart · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
commit 08ab6e6f5ef2a477119499232507112ce05bd9f0
diff --git a/docs/docs/v2/api/classes/AtomTemplate.mdx b/docs/docs/v2/api/classes/AtomTemplate.mdx
@@ -19,13 +19,13 @@ export const AtomKeyDesc = () => (
   </>
 )
 
-The object returned from [the `atom()` factory](/not-done?path=../factories/atom). Instances of this class are passed to most of Zedux's hooks and injectors.
+The object returned from [the `atom()` factory](../factories/atom). Instances of this class are passed to most of Zedux's hooks and injectors.
 
 An atom template defines a skeleton that Zedux will use to create [atom instances](./AtomInstance) on demand.
 
 ## Creation
 
-Use [the `atom()` factory](/not-done?path=../factories/atom) to create atom templates:
+Use [the `atom()` factory](../factories/atom) to create atom templates:
 
 ```ts
 import { AtomTemplate, atom } from '@zedux/react'
@@ -60,35 +60,35 @@ When creating your own, custom atom types, you'll usually want to extend this cl
   <Item name="dehydrate">
     A function. Can be undefined.
 
-    A reference to the [`dehydrate` atom config option](/not-done?path=../types/AtomConfig#dehydrate) passed to [the `atom()` factory](/not-done?path=../factories/atom), if any.
+    A reference to the [`dehydrate` atom config option](/not-done?path=../types/AtomConfig#dehydrate) passed to [the `atom()` factory](../factories/atom), if any.
 
   </Item>
   <Item name="tags">
     An array of strings. Can be undefined.
 
-    A reference to the [`tags` atom config option](/not-done?path=../types/AtomConfig#tags) passed to [the `atom()` factory](/not-done?path=../factories/atom), if any.
+    A reference to the [`tags` atom config option](/not-done?path=../types/AtomConfig#tags) passed to [the `atom()` factory](../factories/atom), if any.
 
     If the ecosystem has [tags configured](./Ecosystem#tags), these tags will be checked against the ecosystem's to warn about unsafe atom templates being used in certain environments.
 
   </Item>
   <Item name="hydrate">
     A function. Can be undefined.
 
-    A reference to the [`hydrate` atom config option](/not-done?path=../types/AtomConfig#hydrate) passed to [`atom()`](/not-done?path=../factories/atom), if any.
+    A reference to the [`hydrate` atom config option](/not-done?path=../types/AtomConfig#hydrate) passed to [`atom()`](../factories/atom), if any.
 
   </Item>
   <Item name="key">
     A string.
 
-    This is the key string passed as the first argument to [the `atom()` factory](/not-done?path=../factories/atom).
+    This is the key string passed as the first argument to [the `atom()` factory](../factories/atom).
 
     <AtomKeyDesc />
 
   </Item>
   <Item name="ttl">
     A number. Can be undefined.
 
-    This is the [`ttl` atom config option](/not-done?path=../types/AtomConfig#ttl) passed to [the `atom()` factory](/not-done?path=../factories/atom), if any.
+    This is the [`ttl` atom config option](/not-done?path=../types/AtomConfig#ttl) passed to [the `atom()` factory](../factories/atom), if any.
 
     If not set, instances of this atom will live forever unless configured with [`.setTtl()`](/not-done?path=./AtomApi#setttl) on an AtomApi returned by the state factory.
 
@@ -140,7 +140,7 @@ When creating your own, custom atom types, you'll usually want to extend this cl
     override = (newValue) => newAtom
     ```
 
-    Accepts any of the same [value types](/not-done?path=../factories/atom#value) that [the `atom()` factory](/not-done?path=../factories/atom) accepts. The state, promise, and exports type of the new value should match the corresponding types in the overridden atom. TypeScript will enforce this.
+    Accepts any of the same [value types](../factories/atom#value) that [the `atom()` factory](../factories/atom) accepts. The state, promise, and exports type of the new value should match the corresponding types in the overridden atom. TypeScript will enforce this.
 
     Returns the new atom template. See the [overrides walkthrough](../../../walkthrough/overrides) for more details.
 
@@ -149,5 +149,5 @@ When creating your own, custom atom types, you'll usually want to extend this cl
 
 ## See Also
 
-- [`atom()`](/not-done?path=../factories/atom)
+- [`atom()`](../factories/atom)
 - [The Configuring Atoms walkthrough](../../../walkthrough/configuring-atoms)
diff --git a/docs/docs/v2/api/classes/Signal.mdx b/docs/docs/v2/api/classes/Signal.mdx
@@ -7,7 +7,7 @@ import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
 
 The object returned by [`injectSignal`](../injectors/injectSignal). Signals are reactive state containers. Each signal holds a value and provides methods for accessing and updating that value. In Zedux, the term "signal" refers to an instance of this class.
 
-Atoms themselves are signals. That simply means the [AtomInstance](./AtomInstance) class extend this class. An atom can also contain many inner signals. When a signal is returned from an [atom state factory](/not-done?path=../factories/atom#valueorfactory), the atom becomes a thin wrapper around the returned signal.
+Atoms themselves are signals. That simply means the [AtomInstance](./AtomInstance) class extend this class. An atom can also contain many inner signals. When a signal is returned from an [atom state factory](../factories/atom#valueorfactory), the atom becomes a thin wrapper around the returned signal.
 
 [Mapped signals](/not-done?path=./MappedSignal) are also signals themselves.
 

diff --git a/docs/docs/v2/api/classes/ZeduxNode.mdx b/docs/docs/v2/api/classes/ZeduxNode.mdx
@@ -165,7 +165,7 @@ Every node has the following **readonly** properties:
   <Item name="id">
     A string. The unique id of this node. Zedux always tries to make this somewhat human-readable for easier debugging.
 
-    For nodes that take params, the id is the combination of the node template's key and a deterministic stringification of the params. A node template's "key" can the string passed to the [`atom()`](/not-done?path=../factories/atom) factory for atoms or the selector function's name for selectors See [`ecosystem.hash()`](./Ecosystem#hash) or [`node.params`](#params) for more details on how params are stringified.
+    For nodes that take params, the id is the combination of the node template's key and a deterministic stringification of the params. A node template's "key" can the string passed to the [`atom()`](../factories/atom) factory for atoms or the selector function's name for selectors See [`ecosystem.hash()`](./Ecosystem#hash) or [`node.params`](#params) for more details on how params are stringified.
 
     ```ts
     ecosystem.getNode(atom('a', null)).id // 'a'

diff --git a/docs/docs/v2/api/factories/atom.mdx b/docs/docs/v2/api/factories/atom.mdx
@@ -0,0 +1,235 @@
+---
+id: atom
+title: atom
+---
+
+import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
+import { AtomKeyDesc } from '../classes/AtomTemplate.mdx'
+
+```ts
+import { atom } from '@zedux/react'
+```
+
+Where it all starts. `atom()` is a factory for creating atom templates. Zedux creates atoms from these templates as you use them in various hooks and injectors.
+
+An atom template is actually an instance of [the AtomTemplate class](../classes/AtomTemplate).
+
+## Example
+
+```tsx live ecosystemId=atom/example resultVar=App version=2
+const simpleAtom = atom('simple', 'Hello, world!')
+
+const complexAtom = atom(
+  'complex',
+  () => {
+    const signal = injectSignal({ date: new Date() })
+
+    injectEffect(() => {
+      const intervalId = setInterval(
+        () => signal.set({ date: new Date() }),
+        1000
+      )
+
+      return () => clearInterval(intervalId)
+    }, [])
+
+    return signal
+  },
+  {
+    flags: ['side-effect'],
+  }
+)
+
+function App() {
+  const simple = useAtomValue(simpleAtom)
+  const { date } = useAtomValue(complexAtom)
+
+  return (
+    <>
+      <div>simple state: {simple}</div>
+      <div>complex state: {date.toLocaleTimeString()}</div>
+    </>
+  )
+}
+```
+
+## Signature
+
+<Tabs>
+  {tab1(`atom = (key, valueOrFactory, config?) => newAtom`)}
+  {tab2(`declare const atom: {
+    // Query Atoms
+    <
+      State = any,
+      Params extends any[] = [],
+      Exports extends Record<string, any> = None
+    >(
+      key: string,
+      value: (...params: Params) => AtomApi<{
+        Exports: Exports
+        Promise: any
+        Signal: undefined
+        State: Promise<State>
+      }>,
+      config?: AtomConfig<State>
+    ): AtomTemplateRecursive<{
+      State: PromiseState<State>
+      Params: Params
+      Events: None
+      Exports: Exports
+      Promise: Promise<State>
+    }>\n
+    // Signals
+    <
+      StateType,
+      EventsType extends Record<string, any> = None,
+      Params extends any[] = [],
+      Exports extends Record<string, any> = None,
+      PromiseType extends AtomApiPromise = undefined,
+      ResolvedState = StateType
+    >(
+      key: string,
+      value: (...params: Params) =>
+        | Signal<{
+            Events: EventsType
+            Params: any
+            State: StateType
+            Template: any
+          }>
+        | AtomApi<{
+            Exports: Exports
+            Promise: PromiseType
+            Signal: Signal<{
+              Events: EventsType
+              Params: any
+              State: StateType
+              Template: any
+            }>
+            State: StateType
+          }>
+        | Signal<{
+            Events: EventsType
+            Params: any
+            ResolvedState: ResolvedState
+            State: StateType
+            Template: any
+          }>
+        | AtomApi<{
+            Exports: Exports
+            Promise: PromiseType
+            Signal: Signal<{
+              Events: EventsType
+              Params: any
+              ResolvedState: ResolvedState
+              State: StateType
+              Template: any
+            }>
+            State: StateType
+          }>,
+      config?: AtomConfig<StateType>
+    ): AtomTemplateRecursive<{
+      State: StateType
+      Params: Params
+      Events: EventsType
+      Exports: Exports
+      Promise: PromiseType
+      ResolvedState: ResolvedState
+    }>\n
+    // Catch-all
+    <
+      State = any,
+      Params extends any[] = [],
+      Exports extends Record<string, any> = None,
+      Events extends Record<string, any> = None,
+      SignalType extends
+        | Signal<{
+            Events: Events
+            Params: any
+            State: State
+            Template: any
+          }>
+        | undefined = undefined,
+      PromiseType extends AtomApiPromise = undefined
+    >(
+      key: string,
+      value: AtomValueOrFactory<{
+        Exports: Exports
+        Params: Params
+        Promise: PromiseType
+        Signal: SignalType
+        State: State
+      }>,
+      config?: AtomConfig<State>
+    ): AtomTemplateRecursive<{
+      Events: Events
+      Exports: Exports
+      Params: Params
+      Promise: PromiseType
+      State: State
+    }>
+  }
+`)}
+
+</Tabs>
+
+<Legend>
+  <Item name="key">
+    Required. A string.
+
+    This key must be unique **except** when creating [atom overrides](../../../walkthrough/overrides).
+
+    <AtomKeyDesc />
+
+    :::tip
+    Currently, Zedux leaves it up to you to ensure keys are unique across your codebase. As such, it's recommended to use a namespace-based naming convention - e.g. based on your project's file structure - to minimize the chance of conflicts.
+
+    ```ts
+    const accountDetailsAtom = atom('dashboard/account/details', ...)
+    const registrationFormAtom = atom('signup/registrationForm', ...)
+    ```
+    :::
+
+  </Item>
+  <Item name="valueOrFactory">
+    Required. Can be any of the following:
+
+    - A raw value. Can be anything except a function. When the atom is instantiated, this value as-is will be its initial state.
+
+    - A state factory function that returns a raw value. That raw value can be anything (including a function). The returned value will be the atom instance's initial state.
+
+    - A state factory function that returns a [signal](../classes/Signal). When the atom is instantiated, the new atom instance will become a thin wrapper around the returned signal, forwarding events and state changes between it and the atom's own observers.
+
+    - A state factory function that returns an [AtomApi](/not-done?path=../classes/AtomApi) instance.
+
+      The Atom API's value can be any of the following:
+
+      - A raw value. Can be anything. This value will be the atom instance's initial state.
+
+      - A signal. The atom instance will become a thin wrapper around the returned signal, forwarding events and state changes between it and the atom's own observers.
+
+      - A promise. This will turn the atom into a [query atom](../../../walkthrough/query-atoms).
+
+        The Atom API's exports will be set as the atom instance's `.exports`.
+
+        The Atom API's promise will be set as the atom instance's `.promise`.
+
+        Any [`ttl`](/not-done?path=../classes/AtomApi#ttl) configured in the returned Atom API will control the atom instance's destruction timing.
+
+  </Item>
+  <Item name="config">
+    Optional. An [AtomConfig](/not-done?path=../types/AtomConfig) object.
+  </Item>
+  <Item name="Returns">
+    An [atom template](../classes/AtomTemplate).
+
+    Zedux will manage creating and maintaining instances of the atom template as you use it in various hooks, injectors, and ecosystem methods.
+
+  </Item>
+</Legend>
+
+## See Also
+
+- [The `AtomTemplate` class](../classes/AtomTemplate)
+- [The `AtomApi` class](/not-done?path=../classes/AtomApi)
+- [The Quick Start](../../../walkthrough/quick-start)
+- [The Configuring Atoms walkthrough](../../../walkthrough/configuring-atoms)
diff --git a/docs/docs/v2/api/glossary.mdx b/docs/docs/v2/api/glossary.mdx
@@ -86,7 +86,7 @@ An atom that contains one or more [`inject`](/not-done?path=./injectors/inject)
 
 ### State Factory
 
-A function passed to [`atom()`](/not-done?path=./factories/atom) (or other atom factory functions like [`ion()`](/not-done?path=./factories/ion)). This function is called to produce the initial value of the atom instance. It also runs every time an atom instance reevaluates.
+A function passed to [`atom()`](./factories/atom) (or other atom factory functions like [`ion()`](/not-done?path=./factories/ion)). This function is called to produce the initial value of the atom instance. It also runs every time an atom instance reevaluates.
 
 These are similar to render functions in React. Except of course they return state instead of UI.
 

diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -177,6 +177,11 @@ module.exports = {
           label: 'Injectors',
           items: ['v2/api/injectors/injectSignal'],
         },
+        {
+          type: 'category',
+          label: 'Factories',
+          items: ['v2/api/factories/atom'],
+        },
         'v2/api/glossary',
       ],
     },