pullstate

Pullstate allows you to decouple state from the React component tree. Instead of passing state down through props (prop drilling), you define stores in separate files and import them directly into any component that needs them.

Components 'pull' the state they need using useState() hooks, and any part of the application can 'push' updates by calling update() on the store. This creates an 'omnipresent' state that is accessible globally without requiring a React Context provider at the root of your tree.

When creating an Async Action using createAsyncAction, you can provide a second argument containing a hooks object. This object allows you to intercept the action lifecycle at three specific stages: before the action runs (short-circuiting), after the action completes (post-action), or when deciding whether to use a cached result (cache-breaking).

In server-rendering environments using a centralized Pullstate "Core" and <PullstateProvider>, the stores object is provided within the hook arguments. For client-side only applications, you should import and use your stores directly instead of relying on the stores argument.

const searchPicturesForTag = createAsyncAction(
  async ({ tag }) => {
    // action code
  },
  {
    postActionHook,
    shortCircuitHook,
    cacheBreakHook
  }
);

Async Actions are a feature in pullstate designed to handle asynchronous state transitions (like API calls) without cluttering your stores with manual loading and error state variables (e.g., userLoading, userLoadError).

They solve two primary problems:

1. Boilerplate Reduction: They allow views to naturally listen for and initiate asynchronous state, removing the need for manual lifecycle management in componentDidMount() or useEffect() hooks.
2. Server-Side Rendering (SSR) Support: They provide a mechanism to resolve an application's asynchronous state before rendering to the user, avoiding the verbose manual try/catch patterns typically required to pre-fetch data and update stores during SSR.

Any action using useBeckon() in the current render tree can have its state resolved on the server before rendering to the client. This enables dynamic page generation.

Requirement: To work correctly, your data-fetching functions must be "isomorphic" or "universal" (capable of running on both the server and the client), such as those provided by Apollo Client or Wildcard API.

// The action must be isomorphic
const searchPicturesForTag = PullstateCore.createAsyncAction(async ({ tag }) => {
  const result = await PictureApi.searchWithTag(tag);
  // ... handle result
});

// In the component, useBeckon will be pre-resolved on the client after SSR
export const PictureExample = (props: { tag: string }) => {
  const [finished, result] = searchPicturesForTag.useBeckon({ tag: props.tag });

  if (!finished) return <div />;
  // ...
};

When writing a reaction function, you receive both a draft and an original object. To ensure optimal performance, follow these rules:

• To mutate/change state: Use the draft object. This uses Immer's proxy mechanism to track changes.
• To read/reference state: Use the original object. Referencing values directly on the draft object can incur a performance penalty due to the internal workings of Immer's JavaScript proxies. Using original provides a plain object of your state for faster read operations.

When using server-rendering, you must create a central reference for all your stores to ensure consistency. This is achieved by using createPullstateCore(), passing an object that contains all your instantiated stores. This core instance acts as the central registry for your application's state in a server-rendered environment.

// 1. Define and instantiate your stores
import { Store } from "pullstate";

interface IUIStore {
  isDarkMode: boolean;
}

export const UIStore = new Store<IUIStore>({
  isDarkMode: true,
});

// 2. Create the PullstateCore to centralize stores for server-rendering
import { createPullstateCore } from "pullstate";

export const PullstateCore = createPullstateCore({
  UIStore
});

To add pullstate to your project, use the following command with yarn:

yarn add pullstate

You can monitor Pullstate stores using the Redux Devtools browser extension. To enable this, use the registerInDevtools function and pass an object containing the stores you wish to monitor. This registration should be performed after your Store definitions have been initialized.

Once registered, each store will appear in the Redux Devtools tab, allowing you to inspect state changes and history.

import { registerInDevtools, Store } from "pullstate";

// Store definition
const ExampleStore = new Store({
  //...
});

// Register as many or as few Stores as you would like to monitor in the devtools
registerInDevtools({
  ExampleStore,
});

To modify existing content:

• Docs: Navigate to the docs/ directory and edit the corresponding .md file.
• Blog Posts: Navigate to the website/blog/ directory and edit the corresponding .md file.

Ensure you preserve the frontmatter block (containing id and title) at the top of the file to maintain correct routing and display.