ion

import { ion } from '@zedux/react'

A factory for creating ion templates. Ions are a type of atom that specialize in selection and derivation operations.

Ions are loosely based off of Recoil's selectors.

Example

Unlike Recoil selectors, ions don't implicitly hijack setState calls. Use exports to explicitly set state where needed.

Live Sandbox

12345678910111213141516171819202122232425262728

const tempFahrenheit = atom('tempFahrenheit', 32)



const tempCelsius = ion('tempCelsius', ({ get, getInstance }) =>

api(((get(tempFahrenheit) - 32) * 5) / 9).setExports({

setTempC: newValue =>

getInstance(tempFahrenheit).setState((newValue * 9) / 5 + 32),

})

)



function TempCelsius() {

const [tempF, setTempF] = useAtomState(tempFahrenheit)

const [tempC, { setTempC }] = useAtomState(tempCelsius)



const addTenCelsius = () => setTempC(tempC + 10)

const addTenFahrenheit = () => setTempF(tempF + 10)



return (

<div>

Temp (Celsius): {Math.round(tempC)}

<br />

Temp (Fahrenheit): {Math.round(tempF)}

<br />

<button onClick={addTenCelsius}>Add 10 Celsius</button>

<br />

<button onClick={addTenFahrenheit}>Add 10 Fahrenheit</button>

</div>

)

}

This is better in pretty much every way imaginable. Exports "just work" with editor go-to definition. They give you more control and they're beautifully explicit which reduces cognitive load, bugs, surprises, all that stuff.

Zedux history

Ions used to have 4 parameters. Back then, the 4th param was the optional config object, and the 3rd was a Recoil-esque setter interceptor. We removed it because exports already handle this, and much more elegantly.

Signature

Simplified

ion = (key, stateFactory, config?) => newIon

TypeScript

declare const ion: {
// Query Atoms
<
  State = any,
  Params extends any[] = [],
  Exports extends Record<string, any> = Record<string, never>
>(
  key: string,
  value: (
    getters: AtomGetters,
    ...params: Params
  ) => AtomApi<{
    Exports: Exports
    Promise: any
    State: Promise<State>
    Store: undefined
  }>,
  config?: AtomConfig<State>
): IonTemplate<{
  State: PromiseState<State>
  Params: Params
  Exports: Exports
  Store: Store<PromiseState<State>>
  Promise: Promise<State>
}>

// Custom Stores
<
  StoreType extends Store<any> = Store<any>,
  Params extends any[] = [],
  Exports extends Record<string, any> = Record<string, never>,
  PromiseType extends AtomApiPromise = undefined
>(
  key: string,
  get: (
    getters: AtomGetters,
    ...params: Params
  ) =>
    | StoreType
    | AtomApi<{
        Exports: Exports
        Promise: PromiseType
        State: StoreStateType<Store>
        Store: StoreType
      }>,
  config?: AtomConfig<StoreStateType<StoreType>>
): IonTemplate<{
  State: StoreStateType<StoreType>
  Params: Params
  Exports: Exports
  Store: StoreType
  Promise: PromiseType
}>

// No Store
<
  State = any,
  Params extends any[] = [],
  Exports extends Record<string, any> = Record<string, never>,
  PromiseType extends AtomApiPromise = undefined
>(
  key: string,
  get: (
    getters: AtomGetters,
    ...params: Params
  ) =>
    | AtomApi<{
        Exports: Exports
        Promise: PromiseType
        State: State
        Store: undefined
      }>
    | State,
  config?: AtomConfig<State>
): IonTemplate<{
  State: State
  Params: Params
  Exports: Exports
  Store: Store<State>
  Promise: PromiseType
}>

// Catch-all
<
  State = any,
  Params extends any[] = [],
  Exports extends Record<string, any> = Record<string, never>,
  StoreType extends Store<any> = Store<any>,
  PromiseType extends AtomApiPromise = undefined
>(
  key: string,
  get: IonStateFactory<{
    State: State
    Params: Params
    Exports: Exports
    Store: StoreType
    Promise: PromiseType
  }>,
  config?: AtomConfig<State>
): IonTemplate<{
  State: State
  Params: Params
  Exports: Exports
  Store: StoreType
  Promise: PromiseType
}>
}

key

Required. A string.

This key must be unique except when creating atom overrides.

The key is the key to Dependency Injection - it's how ecosystems know which atom templates to override. It also aids development - many errors will log the key of the atom they originated in. Keys also help with a codebase's grepability.

stateFactory

Required. A function that receives an AtomGetters object as its first param and any params of the ion as its rest params. Can return any of the following:

• A raw value. When the ion template is instantiated, Zedux will create a new store with this value as its initial state.
• A Zedux store. This will become the atom instance's .store.

• An AtomApi instance.

  The Atom API's value can be any of the following:

  • A raw value. Zedux will create a new store with this value as its initial state.
  • A Zedux store. This will be the instance's .store.
  • A promise. This will turn the atom into a query atom.

  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.

config

Optional. An AtomConfig object.

Returns

An IonTemplate instance.

See Also

• The atom() factory
• The Selectors walkthrough
• The IonTemplate class