api

import { api } from '@zedux/react'

A factory for creating AtomApis.

Examples

Miscellaneous:

import { api } from '@zedux/react'

const myApi = api()
const withValue = api('some value')
const withStore = api(injectStore())
const withExports = api(val).setExports({ ...myExports })
const withPromise = api(val).setPromise(myPromise)
const cloningApis = api(myApi).addExports(withExports.exports)
const addingExports = api(withExports).addExports({ ...moreExports })
const overwritingExports = api(withExports).setExports({ ...newExports })
const settingTtl = api().setTtl(0)
const ttlPromise = api().setTtl(myPromise)
const ttlObservable = api().setTtl(my$)

// query atoms:
return api(myPromise)

Signature

Simplified

api = (value?, wrap?) => atomApi

TypeScript

declare const api: {
  // Custom Stores (AtomApi cloning)
  <
    StoreType extends Store<any> = Store<any>,
    Exports extends Record<string, any> = Record<string, never>,
    PromiseType extends AtomApiPromise = undefined
  >(
    value: AtomApi<{
      Exports: Exports
      Promise: PromiseType
      State: StoreStateType<StoreType>
      Store: StoreType
    }>
  ): AtomApi<{
    Exports: Exports
    Promise: PromiseType
    State: StoreStateType<StoreType>
    Store: StoreType
  }>

  // Custom Stores (normal)
  <StoreType extends Store<any> = Store<any>>(value: StoreType): AtomApi<{
    Exports: Record<string, never>
    Promise: undefined
    State: StoreStateType<StoreType>
    Store: StoreType
  }>

  // No Value
  (): AtomApi<{
    Exports: Record<string, never>
    Promise: undefined
    State: undefined
    Store: undefined
  }>

  <
    State = undefined,
    Exports extends Record<string, any> = Record<string, never>,
    PromiseType extends AtomApiPromise = undefined
  >(): AtomApi<{
    Exports: Exports
    Promise: PromiseType
    State: State
    Store: undefined
  }>

  // No Store (AtomApi cloning)
  <
    State = undefined,
    Exports extends Record<string, any> = Record<string, never>,
    PromiseType extends AtomApiPromise = undefined
  >(
    value: AtomApi<{
      Exports: Exports
      Promise: PromiseType
      State: State
      Store: undefined
    }>
  ): AtomApi<{
    Exports: Exports
    Promise: PromiseType
    State: State
    Store: undefined
  }>

  // No Store (normal)
  <State = undefined>(value: State): AtomApi<{
    Exports: Record<string, never>
    Promise: undefined
    State: State
    Store: undefined
  }>

  // Catch-all
  <
    State = undefined,
    Exports extends Record<string, any> = Record<string, never>,
    StoreType extends Store<State> = Store<State>,
    PromiseType extends AtomApiPromise = undefined
  >(
    value:
      | State
      | StoreType
      | AtomApi<{
          Exports: Exports
          Promise: PromiseType
          State: State
          Store: StoreType
        }>
  ): AtomApi<{
    Exports: Exports
    Promise: PromiseType
    State: State
    Store: StoreType
  }>
}

value

Optional. Can be absolutely anything.

If a Zedux store is passed, it will be set as the returned api's .store property. Otherwise, .store will be undefined.

If a promise is passed and this api is returned from an atom state factory, the atom will become a query atom.

If another Atom API is passed, api() clones it - returning a new AtomApi instance with all the properties of the passed api copied over (shallowly).

wrap

Optional. A boolean. Default true.

Whether to automatically wrap all exported functions in ecosystem.batch() calls.

Zedux wraps all exported functions by default. Pass false to prevent this. This wrapping has some overhead, but is recommended to leave enabled unless you know what you're doing. Forgetting to batch updates can lead to state tearing in rare cases.

Returns

An AtomApi instance.

See Also

• The Atom APIs walkthrough
• The AtomApi class