helux

The Helux base API provides a set of fundamental functions for state management, reactivity, and data flow. These functions can be categorized into several core capabilities:

State Creation

• Atoms: Use atom (returns a tuple) or atomx (returns a dictionary) to create basic state objects.
• Shared State: Use share (returns a tuple) or sharex (returns a dictionary) to create dictionary-type atom objects.
• Granular Reactivity: Use signal for DOM-level updates or block/dynamicBlock for block-level updates.

Derivation and Mutation

• Derivation (Read-only): Define derived state using derive (single) or deriveDict (batch). For asynchronous tasks, use defineDeriveTask or defineDeriveFnItem to benefit from automatic dependency type inference. Trigger derivations manually with runDerive or runDeriveTask.
• Mutation (Writeable): Define mutable derived functions using mutate (single) or mutateDict (batch). Trigger them manually with runMutate or runMutateTask.

Actions and Side Effects

• Actions: Create synchronous or asynchronous functions to modify state using action.
• Observation: Monitor data changes using watch or watchEffect (which runs immediately and collects dependencies on the first run).
• Events: Use emit to dispatch events and on to listen for them.

Data Synchronization

• Two-way Binding: Use syncer for shallow object synchronization or sync for deep object synchronization to assist with two-way data binding.

Helux is a high-performance state engine that integrates atom, signal, and dependency tracking. It is designed for fine-grained reactive updates and is compatible with all React-like libraries, including React 18.

Key features include:

• High Performance: Built on limu (an immutable JS library) with built-in dependency tracking.
• DDD Friendly: atom supports arbitrary data structures with built-in dependency collection, making it suitable for Domain-Driven Design without needing to split state into tiny pieces.
• Fine-grained Updates: Built-in signal mechanism allows for DOM or block-level updates with zero hooks.
• Async Management: A built-in loading module manages asynchronous task states and error propagation to components and plugins.
• Two-way Binding: A sync API series supports two-way binding, simplifying form handling.
• Reactive Objects: Built-in reactive objects allow data changes to directly drive UI rendering.
• Modular Architecture: define APIs facilitate modular state abstraction for large-scale frontend applications.
• Flexible Derivation:
  • Mutable Derivation: For scenarios where changes to specific nodes in a shared object should trigger updates in other nodes with minimal granularity.
  • Full Derivation: For scenarios where fine-grained updates are not required.
  • Both support asynchronous tasks and manual re-triggering.
• Extensibility: Includes an event system and a middleware/plugin system that integrates with the Redux ecosystem.
• Type Safety: 100% TypeScript codebase.

Helux provides a comprehensive set of APIs for state management, categorized into Base APIs, Shared Context, Hooks, and Utilities.

Base APIs

Used for creating state containers and defining reactive logic:

• Atoms: atom (returns tuple), atomx (returns dictionary), share (dictionary-type atom, returns tuple), sharex (dictionary-type atom, returns dictionary).
• Granular Updates: signal (DOM-level updates), block (block-level updates), dynamicBlock (dynamic block updates during component rendering).
• Derivations: derive (single full derivation), deriveDict (batch full derivations), defineDeriveTask (async task helper), defineDeriveFnItem (async task helper), runDerive (manual trigger), runDeriveTask (manual async trigger).
• Mutations: mutate (single mutable derivation), mutateDict (batch mutable derivations), runMutate (manual trigger), runMutateTask (manual async trigger).
• Actions & Side Effects: action (sync/async state modifiers), watch (data change listeners), watchEffect (immediate listeners with dependency collection), syncer/sync (two-way binding helpers), emit (event emission), on (event listening).

Helux supports real-time dependency collection during component rendering. When you use useAtom to access specific properties of an object stored in an atom, helux tracks which properties were accessed. This ensures that a component only re-renders when the specific properties it depends on change, rather than re-rendering on any change to the atom.

import { useAtom } from 'helux';
const [objAtom, setObj] = atom({ a: 1, b: { b1: 1 } });

// Modify the draft and generate a new state with shared data structure. 
// The current modification will only trigger the rendering of the Demo1 component.
setObj((draft) => (draft.a = Math.random()));

function Demo1() {
  const [obj] = useAtom(objAtom);
  // Trigger re-rendering only when obj.a changes
  return <h1>{obj.a}</h1>;
}

function Demo2() {
  const [obj] = useAtom(objAtom);
  // Trigger re-rendering only when obj.b.b1 changes
  return <h1>{obj.b.b1}</h1>;
}