react-sweet-state

While sweet-state uses the React Context API under the hood, it is designed to solve the inherent limitations and common pitfalls of using raw Context at scale.

Why use sweet-state instead of raw Context API?

Raw Context API has several limitations that sweet-state addresses:

• Performance: Context is not designed for frequent updates and has performance limitations regarding re-renders. sweet-state provides mechanisms to prevent unnecessary re-renders.
• Async Operations: Handling asynchronous operations in raw Context is difficult; sweet-state provides a structured way to handle them.
• Selectors: Raw Context does not natively support selectors; sweet-state includes selector support to optimize updates.
• Debuggability: sweet-state integrates with Devtools to improve visibility into state changes.
• Safety: sweet-state protects consumers from common mistakes related to the asynchronous nature of React setState and provides better handling for provider-less scenarios.

sweet-state is influenced by Redux but is designed to make modern React patterns first-class citizens. Use sweet-state if you want to avoid the 'all-or-nothing' state ownership model of Redux and prefer a library that promotes composition and integration with other state management solutions (like Apollo or GraphQL).

Shared Features

• Debuggability: Both support Redux Devtools.
• Selectors: Both support state selectors.
• Testability: Both use similar testing strategies for actions and selectors.

Key Differences

• Interoperability: Redux works best when it owns the entire state; sweet-state is designed to be composed with other solutions.
• Boilerplate: sweet-state uses a pattern similar to redux-thunk actions but eliminates the need for reducers, significantly reducing boilerplate.
• Nesting: Unlike Redux, which relies on a Provider that can make component nesting challenging, sweet-state has no Provider concept, allowing components to be more resilient and easily nested/mixed.

While react-sweet-state promotes independent micro-Stores, using a single global instance for each Store type can be limiting. Container components solve this by allowing you to create multiple independent instances of the same Store type.

Containers can be used in three ways:

1. Locally scoped (Default): Creates a Store instance accessible only to its children. These instances are automatically cleaned up when the last Container accessing them unmounts.
2. Global singleton (isGlobal): Acts as a transparent link to the "default" global instance of that Store type.
3. Scoped global (scope): Creates or retrieves a global instance prefixed with a specific scope ID. This allows you to have multiple distinct global instances (e.g., counter-1, counter-2) that can be shared across different parts of the component tree.

You can change the scope of a Store (from local to global or scoped) by moving the Container in the tree or adding props, without needing to modify the child components or hooks.

import { createStore, createContainer, createHook } from 'react-sweet-state';

export const CounterContainer = createContainer();

const Store = createStore({
  containedBy: CounterContainer,
  initialState: { count: 0 },
  actions: {
    increment: () => ({ setState }) => {
      const currentCount = getState().count;
      setState({ count: currentCount + 1 });
    },
  },
});

const useCounter = createHook(Store);

export const CounterButton = () => {
  const [{ count }, { increment }] = useCounter();
  return <button onClick={increment}>{count}</button>;
};

To use react-sweet-state with TypeScript, define your State and Actions types. Use the Action<State> type for your action implementations. Most create* methods (like createStore, createSubscriber, and createHook) can infer their generics from the Store instance, so manual typing is often unnecessary.

Key steps:

1. Define the State type.
2. Define actions using the Action<State> type.
3. Create a Container using createContainer().
4. Initialize the Store with createStore<State, Actions>({ initialState, actions, containedBy: Container }).
5. Derive hooks and subscribers from the Store.

import {
  createStore,
  createSubscriber,
  createHook,
  createContainer,
  Action,
} from 'react-sweet-state';

type State = { count: number };
type Actions = typeof actions;

const initialState: State = {
  count: 0,
};

const actions = {
  increment:
    (by = 1): Action<State> =>
    ({ setState, getState }) => {
      setState({
        count: getState().count + by,
      });
    },
};

const CounterContainer = createContainer();

const Store = createStore<State, Actions>({
  initialState,
  actions,
  containedBy: CounterContainer,
});

const CounterSubscriber = createSubscriber(Store);
const useCounter = createHook(Store);

When using a selector function with createHook or createSubscriber, you must adjust the generic arguments of the resulting type to reflect the selector's output and its required props.

Without Selector Props

If the selector only takes state, the type arguments are (SelectorState, Actions):

type SelectorState = boolean;
const selector = (state: State): SelectorState => state.count > 0;

const useCounter: HookFunction<SelectorState, Actions> = createHook(Store, {
  selector,
});

With Selector Props

If the selector takes state and props, the type arguments are (SelectorState, Actions, SelectorProps):

type SelectorProps = { min: number };
type SelectorState = boolean;
const selector = (state: State, props: SelectorProps): SelectorState => state.count > props.min;

const useCounter: HookFunction<SelectorState, Actions, SelectorProps> = createHook(Store, {
  selector,
});