Skip to main content

AtomApi

Atom APIs dynamically define certain integral properties of an atom. These properties do not fit well in the injector paradigm, as they define key characteristics of the atom itself.

These properties include an atom's exports, suspense promise, and custom TTL configuration.

All properties added to an AtomApi except the value and promise should be stable references. .value and .promise are the only properties that won't be ignored on subsequent evaluations.

note

The properties don't have to be stable; Zedux will just ignore the new references on subsequent evaluations.

Creation​

Create AtomApis with the api() factory.

import { api } from '@zedux/react'

const myApi = api()
const withValue = api('some value')
const withStore = api(createStore())
const withExports = api(val).setExports({ ...myExports })
const withPromise = api(val).setPromise(myPromise)
const fromApi = api(myApi)
const addingExports = api(withExports).addExports({ ...moreExports })
const overwritingExports = api(withExports).setExports({ ...newExports })

Usage​

AtomApis can be used to pass stores, promises, and exports around. Ultimately, you'll return only one AtomApi from the state factory.

import { api, atom, injectStore } from '@zedux/react'

const withEvaluator = atom('withEvaluator', () => {
  return api('initial state')
})

const withStore = atom('withStore', () => {
  const store = injectStore('initial state')

  return api(store)
})

const withExports = atom('withExports', () => {
  const store = injectStore('initial state')

  return api(store).setExports({
    someProp: 'some val',
  })
})

const composingApis = atom('composingApis', () => {
  const injectedApi = injectSomethingThatReturnsAnApi()

  return api(injectedApi).addExports({
    additionalExport: 'some val',
  })
})

Properties​

AtomApis expose the following readonly properties:

exports

An object, or undefined if no exports were set.

These are the exports added to this AtomApi via .setExports() and/or .addExports().

promise

The promise set via .setPromise().

Unless the AtomApi's .value is a promise (creating a "query atom"), this promise will be set as the atom instance's suspense .promise (if this AtomApi is returned from the state factory). For query atoms, this property is ignored.

store

If this AtomApi's .value is a store, the store will also be assigned to this property. This is mostly for convenience when working with TypeScript, since the .value property won't retain all the type information of the exact store used.

ttl

The value set via .setTtl() (if any). An AtomInstanceTtl or a function that returns an AtomInstanceTtl. If a function, it will be called when Zedux schedules this atom instance's destruction. Will override any ecosystem- or atom-level ttl for this atom instance (if this AtomApi is returned from the state factory).

value

A reference to the value passed to the api() factory. Can be any raw value or a Zedux store.

If it's a store and this AtomApi is returned from a state factory, the store should be a stable reference that won't change on subsequent evaluations, e.g. by using injectStore().

wrap

A boolean. This will be set to the value passed as the second parameter to api(). If not passed, defaults to true.

See api#wrap.

Methods​

addExports

Accepts an object. The object can contain anything, though all properties should be stable references - memoized functions or ref objects that won't change on subsequent evaluations.

Merges the passed object into any already-set exports on this AtomApi. If no exports have been set yet on this AtomApi, .addExports() sets the exports.

Returns the AtomApi for chaining.

api('val')
.addExports({ a: 1 })
.addExports({ b: 2 })
.addExports({ a: 3 })
.exports // { a: 3, b: 2 }
setExports

The main way to set an AtomApi's exports. Accepts an object. The object can contain anything, though all properties should be stable references - memoized functions or ref objects that won't change on subsequent evaluations.

Overwrites any previously-set exports on this AtomApi.

If this AtomApi is returned from a state factory, these exports will be set as the atom instance's .exports.

Returns the AtomApi for chaining.

const initialExports = api(val).setExports({ ...myExports })
const overwriteExports = api(initialExports).setExports({ ...newExports })
setPromise

Accepts a promise. Sets the .promise property of this AtomApi.

If this AtomApi is returned from a state factory, the promise will be set as the atom instance's .promise and will be used to cause React to suspend.

This promise does not have to be a stable reference, though you should be conscious of when its reference changes since any components using the atom instance will re-suspend when the promise changes (if this AtomApi is returned from the state factory).

Returns the AtomApi for chaining.

setTtl

Accepts an AtomInstanceTtl or a function that returns an AtomInstanceTtl. This will be set as the AtomApi's .ttl property.

If this AtomApi is returned from a state factory, this AtomInstanceTtl will be set as the atom instance's TTL, overriding any atom config and ecosystem-level TTL.

Returns the AtomApi for chaining.

See Also​