Store Actions & Mutations

Relevant source files

The following files were used as context for generating this wiki page:

• src/store.ts
• src/index.ts
• src/provider.tsx
• package.json
• cubic.yaml
• tsconfig.json

The toast notification system utilizes a centralized state management pattern implemented via a ToastStore class. This store serves as the single source of truth for all active notifications, handling the creation, updates, and removal of toast objects. It employs an observer pattern to synchronize state changes with React components, specifically the ToastProvider.

The store is designed with strict type safety and a focus on asynchronous state transitions, such as handling promises and auto-dismissal timers. It ensures that the notification queue remains manageable by enforcing a maximum limit on visible toasts.

Sources: src/store.ts:1-55, src/provider.tsx:12-20, package.json:1-10

Core Data Structures

The system's state revolves around the Toast interface and the ToastType union. These structures define the shape of the data stored within the state array.

Toast Model

Field	Type	Description
id	string	Unique identifier generated using base-36 random string.
message	string | React.ReactNode	The content to display in the notification.
type	ToastType	Category: success, error, info, warning, loading, or default.
duration	number (optional)	Time in milliseconds before auto-removal (default: 4000ms).
action	object (optional)	Interactive button with a label and onClick callback.

Sources: src/store.ts:5-18, src/store.ts:36-37

State Management Architecture

The ToastStore manages an internal array of Toast objects and a list of subscriber functions.

Subscription and Notification

The store implements a subscription mechanism where the ToastProvider registers an observer to receive state updates.

1. Subscribe: Adds an observer function to the observers array and returns an unsubscribe cleanup function.
2. Notify: Iterates through all observers, providing them with a shallow copy of the current toasts array to trigger re-renders.

Sources: src/store.ts:24-34, src/provider.tsx:17-19

Actions and State Mutations

State mutations are performed through three primary methods: add, remove, and update.

Adding Toasts

When a toast is added:

• A unique ID is generated: Math.random().toString(36).substring(2, 9).
• The new toast is prepended to the array.
• The list is truncated using .slice(0, 5) to limit visibility to the 5 most recent items.
• If the type is not loading, a setTimeout is initialized to automatically call remove after the specified duration (defaulting to 4000ms).

Sources: src/store.ts:36-46

Update and Removal

• remove(id): Filters the toasts array to exclude the specified ID and triggers a notification.
• update(id, updates): Maps through the current toasts and merges updates into the object matching the provided ID.

Sources: src/store.ts:49-57

API Implementation

The public toast API wraps the toastStore methods to provide a clean, functional interface for developers.

Static Type Methods

The toast function includes static methods for common notification types, which automatically assign the appropriate ToastType.

Promise Handling

The toast.promise action facilitates state transitions based on the resolution or rejection of an asynchronous operation.

Integration with React

The ToastProvider component consumes the store state via the useEffect hook, ensuring the UI stays in sync with the store's internal array.

// src/provider.tsx:16-20
export function ToastProvider({ theme = "cyber", position = "bottom-right" }: ToastProviderProps) {
  const [toasts, setToasts] = useState<Toast[]>([]);

  useEffect(() => {
    return toastStore.subscribe(setToasts);
  }, []);
  // ... rendering logic
}

The provider uses framer-motion's AnimatePresence to handle entry and exit animations for toasts as they are added or removed from the store array.

Sources: src/provider.tsx:12-25, package.json:20-25

Summary

The Store Actions & Mutations system in @pcstyle/toast provides a robust mechanism for managing notification lifecycles. By decoupling the state logic in ToastStore from the rendering logic in ToastProvider, the system achieves high performance and a clean developer API. Key features include automatic ID generation, a 5-toast visibility limit, auto-dismissal timers, and a specialized promise handler for managing complex asynchronous UI states.