LobeHub Zustand State Management

State Shapes and Types

Import shared store types from @lobechat/types, not @lobechat/database.
Keep lightweight list-item types separate from full detail types; list types must not extend heavy detail types.
Use arrays for whole-list display and id-keyed maps for cached details, with per-item loading state where needed.
Before choosing list/detail shapes, normalized maps or state type sources, read Data structures. Its worked examples load only when relevant.

Action Type Hierarchy

1. Public Actions

Main interfaces for UI components:

Naming: Verb form (createTopic, sendMessage)
Responsibilities: Parameter validation, flow orchestration

2. Internal Actions (`internal_*`)

Core business logic implementation:

Naming: internal_ prefix (internal_createTopic)
Responsibilities: Optimistic updates, service calls, error handling
Should not be called directly by UI

3. Dispatch Methods (`internal_dispatch*`)

State update handlers:

Naming: internal_dispatch + entity (internal_dispatchTopic)
Responsibilities: Calling reducers, updating store

When to Use Reducer vs Simple `set`

Use Reducer Pattern:

Managing object lists/maps (messagesMap, topicMaps)
Optimistic updates
Complex state transitions

Use Simple set:

Toggling booleans
Updating simple values
Setting single state fields

Optimistic Update Pattern

internal_createTopic: async (params) => {
  const tmpId = Date.now().toString();

  // 1. Immediately update frontend (optimistic)
  get().internal_dispatchTopic(
    { type: 'addTopic', value: { ...params, id: tmpId } },
    'internal_createTopic'
  );

  // 2. Call backend service
  const topicId = await topicService.createTopic(params);

  // 3. Refresh for consistency
  await get().refreshTopic();
  return topicId;
},

Delete operations: Don't use optimistic updates (destructive, complex recovery)

Naming Conventions

Actions:

Public: createTopic, sendMessage
Internal: internal_createTopic, internal_updateMessageContent
Dispatch: internal_dispatchTopic State:
ID arrays: topicEditingIds
Maps: topicMaps, messagesMap
Active: activeTopicId
Init flags: topicsInit

Detailed Guides

Action patterns: references/action-patterns.md
Slice organization: references/slice-organization.md

Class-Based Action Implementation

We are migrating slices from plain StateCreator objects to class-based actions.

Pattern

Define a class that encapsulates actions and receives (set, get, api) in the constructor.
Use #private fields (e.g., #set, #get) to avoid leaking internals.
Prefer shared typing helpers:
- StoreSetter<T> from @/store/types for set.
- Pick<ActionImpl, keyof ActionImpl> to expose only public methods.
Export a create*Slice helper that returns a class instance.

type Setter = StoreSetter<HomeStore>;
export const createRecentSlice = (set: Setter, get: () => HomeStore, _api?: unknown) =>
  new RecentActionImpl(set, get, _api);

export class RecentActionImpl {
  readonly #get: () => HomeStore;
  readonly #set: Setter;

  constructor(set: Setter, get: () => HomeStore, _api?: unknown) {
    void _api;
    this.#set = set;
    this.#get = get;
  }

  useFetchRecentTopics = () => {
    // ...
  };
}

export type RecentAction = Pick<RecentActionImpl, keyof RecentActionImpl>;

Composition

In store files, merge class instances with flattenActions (do not spread class instances).
flattenActions binds methods to the original class instance and supports prototype methods and class fields.

const createStore: StateCreator<HomeStore, [['zustand/devtools', never]]> = (...params) => ({
  ...initialState,
  ...flattenActions<HomeStoreAction>([
    createRecentSlice(...params),
    createHomeInputSlice(...params),
  ]),
});

Multi-Class Slices

For large slices that need multiple action classes, compose them in the slice entry using flattenActions.
Use a local PublicActions<T> helper if you need to combine multiple classes and hide private fields.

type PublicActions<T> = { [K in keyof T]: T[K] };

export type ChatGroupAction = PublicActions<
  ChatGroupInternalAction & ChatGroupLifecycleAction & ChatGroupMemberAction & ChatGroupCurdAction
>;

export const chatGroupAction: StateCreator<
  ChatGroupStore,
  [['zustand/devtools', never]],
  [],
  ChatGroupAction
> = (...params) =>
  flattenActions<ChatGroupAction>([
    new ChatGroupInternalAction(...params),
    new ChatGroupLifecycleAction(...params),
    new ChatGroupMemberAction(...params),
    new ChatGroupCurdAction(...params),
  ]);

Store-Access Types

For class methods that depend on actions in other classes, define explicit store augmentations:
- ChatGroupStoreWithSwitchTopic for lifecycle switchTopic
- ChatGroupStoreWithRefresh for member refresh
- ChatGroupStoreWithInternal for curd internal_dispatchChatGroup

Slices That Don't Currently Need `set`

When a slice doesn't write local state (e.g. it delegates to another store or just runs hooks), drop #set and mark the constructor param as _set with void _set to keep the (set, get, api) shape:

export class ToolActionImpl {
  readonly #get: () => ConversationStore;

  constructor(_set: Setter, get: () => ConversationStore, _api?: unknown) {
    void _set;
    void _api;
    this.#get = get;
  }

  approveToolCall = async (id: string) => {
    const { context, hooks } = this.#get();
    await useChatStore.getState().approveToolCalling(id, '', context);
    hooks.onToolCallComplete?.(id, undefined);
  };
}

Drop #set when unused; restore it when a later edit needs set — re-adding costs nothing.
Don't add setNamespace for slices that don't write state.
Don't keep both old slice objects and class actions active at the same time during migration.

zustand