Skip to main content

AtomTemplate

The object returned from the atom() factory. 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 on demand.

Creation​

Use the atom() factory to create atom templates:

import { AtomTemplate, atom } from '@zedux/react'

const exampleAtom = atom('example', 'initial state')

exampleAtom instanceof AtomTemplate // true
note

The _____Atom naming convention comes from Jotai. If it's confusing (templates aren't atoms after all...), you don't have to use it. Feel free to pick your own.

Extending​

When creating your own, custom atom types, you'll usually want to extend this class. Creating your own atom types is an advanced feature and we're not currently documenting it as the internals of these classes may change.

Properties​

dehydrate

A function. Can be undefined.

A reference to the dehydrate atom config option passed to atom(), if any.

flags

An array of strings. Can be undefined.

A reference to the flags atom config option passed to atom(), if any.

The flags that will be checked alongside an ecosystem's flags to warn about unsafe atom templates being used in certain environments.

hydrate

A function. Can be undefined.

A reference to the hydrate atom config option passed to atom(), if any.

key

A string.

This is the key string passed as the first param to atom().

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.
manualHydration

A boolean. Can be undefined.

This is the manualHydration atom config option passed to atom(), if any.

ttl

A number. Can be undefined.

This is the ttl atom config option passed to atom(), if any.

If not set, the ecosystem's atomDefaults.ttl will be used. If the ecosystem doesn't set a default, instances of this atom will live forever by default. Setting this value will override any default.

  • Set to -1 to make this atom's instances live forever.
  • Set to 0 to destroy all instances of this atom as soon as they go stale.
  • Set to any positive integer to make atoms live in a stale state for <ttl> milliseconds before being cleaned up.

This option can be overridden and configured more granularly by the atom instances themselves via AtomApi#setTtl().

Methods​

getInstanceId

Gets a string id for a specific instance of this atom template.

Signature:

getInstanceId = (ecosystem, params?) => id

Accepts an ecosystem and an array of atom params (required if the atom takes params, undefined if not). Uses the ecosystem's id generator to generate a predictable hash of the atom template's key + params combo.

Zedux uses this internally to generate atom instance ids. You won't typically call this.

override

Creates a clone of this atom template, but with a different value.

Signature:

override = (newValue) => newAtom

Accepts any of the same value types that 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 Also​