repository·master·Indexed 19 days ago
https://github.com/omnistac/zeduxA molecular state engine for React (version 2.0.0-rc.19) that combines atomic state management with dependency injection and signals. It functions as both a cache manager and a standard state manager. The ecosystem includes @zedux/atoms for framework-independent atomic models, @zedux/core for composable stores, @zedux/react for React-specific hooks and components, and specialized extensions like @zedux/immer for mutable-style updates and @zedux/machines for state machine logic.
Zedux is a multi-paradigm state management engine for React. It combines a powerful signals implementation with a Dependency Injection (DI)-driven atomic architecture.
It functions as both a cache manager and a state manager, offering features like:
Zedux is a multi-paradigm state management engine for React. It uses a composable store model built on a Dependency Injection (DI) driven atomic architecture. It is designed to scale from simple local state to highly complex, volatile global state (such as web socket-driven trading platforms).
Key characteristics include:
The Zedux API is organized into seven primary categories that define how you interact with the library. Depending on your use case (React integration, core logic, or TypeScript definitions), you will primarily interact with one or more of the following:
An Unrestricted Injector is a special type of injector that relaxes the standard rules of injector usage.
While they must still be called synchronously during the evaluation of an atom state factory, unlike normal injectors, they can be used inside control flow statements (if, for, while) or after early returns.
Common examples include:
injectAtomGetters()injectInvalidate()injectWhy()Zedux is a 'Molecular State Engine for React' designed for high-performance, scalable state management in complex applications.
Its architecture is built on two primary layers that are decoupled to enable powerful Dependency Injection (DI) and inter-store communication:
This separation is specifically designed to handle highly volatile state (e.g., socket-driven applications) and to improve Developer Experience (DevX) and runtime performance compared to traditional Flux-based models.
An Action is an object dispatched to a Zedux store to trigger state changes. Every action must contain a type property of type string. It may optionally include a payload for data and meta for additional metadata.
Conceptually, actions are a subset of ActionChains; an Action is simply an ActionChain with a size of 1.
export interface Action<
Payload = any,
Type extends string = string,
Meta = any
> {
meta?: Meta
payload?: Payload
type: Type
}An AtomSelector is a function used to derive state from atoms. It is a blueprint for pulling data and does not execute until it is called by a consumer. It receives an AtomGetters object as its first parameter, which allows it to retrieve atom values and compose other selectors.
useAtomSelector() (React hook)injectAtomSelector() (Injector)ecosystem.select() (Ecosystem method)select function within another AtomSelector (Composition)AtomSelectors are not atoms and cannot use injectors. Use an Ion instead if you need:
injectMemo().injectStore().injectEffect().AtomApi#setPromise() in an atom.type AtomSelector<T = any, Args extends any[] = []> = (
getters: AtomGetters,
...args: Args
) => TAn Ecosystem is an isolated atom environment. It acts as a container that manages the lifecycle and relationships of atoms and selectors. Every ecosystem provides:
Atom Selector instances.Ecosystems can be used independently of React, making them ideal for testing atoms and selectors in isolation.
The Atom API is a standardized container used to pass the three core "meta data types" of an atom between injectors and state factories:
store objects.You can construct and manipulate these using the api() utility. This pattern is used by built-in injectors like injectPromise().
// Constructing an Atom API
const myApi = api(myStore).setExports(myExports).setPromise(myPromise)
// Accessing the components
const { exports, promise, store } = myApiWhile Atom Selectors are great for simple, inexpensive logic, they lack fine-grained control over re-evaluation. For complex, expensive operations (like sorting or filtering large lists), use Ions.
Ions are special atoms created with the ion() factory. They receive an AtomGetters object as their first parameter, allowing them to behave like atoms while being specifically designed for selector-type operations.
When to use an Ion instead of an Atom Selector:
import { ion } from '@zedux/react'
// An ion that filters and sorts users based on a role
const sortedUsersAtom = ion('sortedUsers', ({ get }, roleFilter: string) => {
const users = get(usersAtom).filter(user => user.role === roleFilter)
return [...users].sort((userA, userB) => userA.name.localeCompare(userB.name))
})
function MyComponent() {
// Access ions just like regular atoms
const adminUsers = useAtomValue(sortedUsersAtom, ['admin'])
}Plugins in Zedux are low-level tools used to implement active control over state flow. Unlike stores, which use passive effects subscribers, plugins hook into the ecosystem level.
They communicate via a bidirectional stream:
Action objects) via a modBus (which is itself a Zedux store).modStore (also a Zedux store). By updating the modStore with specific mod names, the plugin tells the ecosystem which internal events it wants to receive.Ecosystems disable most mod events by default for performance. A plugin must explicitly request them to receive them.
By default, Zedux automatically creates a store for every atom. If you want an atom to use a specific store you created via injectStore, you must return the store from the atom's state factory.
Returning the store tells Zedux: "Don't create a store for me; use this one instead." This allows for joint updates: the atom can update its state internally (via side effects) and externally (via the setState function returned by useAtomState in a component).
const greetingAtom = atom('greeting', () => {
const store = injectStore('Hello, World!')
return store // Returning the store exposes it to consumers
})
function Greeting() {
const [state] = useAtomState(greetingAtom)
return <div>{state}</div>
}