@allternit/gizzi-code 1.0.0

package/src/state/AppStateStore.js

@@ -0,0 +1,439 @@
+/**
+ * @fileoverview Application state store with React integration
+ * @module state/AppStateStore
+ *
+ * Centralized state management using the store pattern with subscription-based
+ * reactivity. Provides React hooks for component integration.
+ */
+import { useState, useEffect, useCallback, useSyncExternalStore } from 'react';
+/**
+ * Default user preferences
+ * @constant {UserPreferences}
+ */
+const DEFAULT_PREFERENCES = {
+    theme: 'system',
+    language: 'en',
+    notifications: {
+        enabled: true,
+        sound: true,
+        desktop: false,
+    },
+    editor: {
+        fontSize: 14,
+        fontFamily: 'monospace',
+        wordWrap: true,
+        lineNumbers: true,
+        tabSize: 2,
+    },
+};
+/**
+ * Initial application state
+ * @constant {AppState}
+ */
+const INITIAL_STATE = {
+    session: null,
+    preferences: DEFAULT_PREFERENCES,
+    messages: [],
+    connectionStatus: 'connecting',
+    isLoading: false,
+    loadingMessage: null,
+    errors: [],
+    currentView: '/',
+    viewState: {},
+    lastUpdated: new Date(),
+};
+/**
+ * Application state store class
+ * Implements the observable store pattern with subscription-based updates
+ *
+ * @example
+ * ```typescript
+ * const store = new AppStateStore();
+ * const unsubscribe = store.subscribe((state, prevState) => {
+ *   console.log('State updated:', state);
+ * });
+ * store.setState({ isLoading: true });
+ * ```
+ */
+export class AppStateStore {
+    constructor(initialState = {}) {
+        this.listeners = new Set();
+        this.isBatching = false;
+        this.pendingUpdates = {};
+        this.state = {
+            ...INITIAL_STATE,
+            ...initialState,
+            lastUpdated: new Date(),
+        };
+    }
+    /**
+     * Gets the current state
+     * @returns {Readonly<AppState>} The current application state
+     */
+    getState() {
+        return Object.freeze({ ...this.state });
+    }
+    /**
+     * Gets a derived value from state using a selector function
+     *
+     * @template T
+     * @param {StateSelector<T>} selector - Function to extract value from state
+     * @returns {T} The selected value
+     * @example
+     * ```typescript
+     * const userName = store.select(state => state.session?.displayName);
+     * ```
+     */
+    select(selector) {
+        return selector(this.state);
+    }
+    /**
+     * Updates the state with partial changes
+     * Automatically notifies all subscribers
+     *
+     * @param {Partial<AppState>} updates - Partial state updates
+     * @param {Object} [options] - Update options
+     * @param {boolean} [options.silent=false] - If true, does not notify subscribers
+     * @returns {Readonly<AppState>} The updated state
+     */
+    setState(updates, options = {}) {
+        if (this.isBatching) {
+            this.pendingUpdates = { ...this.pendingUpdates, ...updates };
+            return this.getState();
+        }
+        const prevState = this.state;
+        this.state = {
+            ...this.state,
+            ...updates,
+            // Merge nested objects
+            preferences: updates.preferences
+                ? { ...this.state.preferences, ...updates.preferences }
+                : this.state.preferences,
+            viewState: updates.viewState
+                ? { ...this.state.viewState, ...updates.viewState }
+                : this.state.viewState,
+            lastUpdated: new Date(),
+        };
+        if (!options.silent) {
+            this.notifyListeners(prevState);
+        }
+        return this.getState();
+    }
+    /**
+     * Batches multiple state updates into a single notification
+     *
+     * @param {() => void} callback - Function containing state updates to batch
+     * @returns {Readonly<AppState>} The final state after all updates
+     * @example
+     * ```typescript
+     * store.batch(() => {
+     *   store.setState({ isLoading: true });
+     *   store.setState({ loadingMessage: 'Fetching data...' });
+     * });
+     * // Subscribers are notified once after both updates
+     * ```
+     */
+    batch(callback) {
+        this.isBatching = true;
+        try {
+            callback();
+        }
+        finally {
+            this.isBatching = false;
+            const pending = this.pendingUpdates;
+            this.pendingUpdates = {};
+            if (Object.keys(pending).length > 0) {
+                return this.setState(pending);
+            }
+        }
+        return this.getState();
+    }
+    /**
+     * Subscribes to state changes
+     *
+     * @param {StateListener} listener - Callback invoked on state changes
+     * @returns {() => void} Unsubscribe function
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        // Immediately notify with current state
+        listener(this.state, this.state);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Subscribes to a specific derived value using a selector
+     * Only notifies when the selected value changes
+     *
+     * @template T
+     * @param {StateSelector<T>} selector - Function to extract value
+     * @param {(value: T) => void} callback - Callback invoked when value changes
+     * @returns {() => void} Unsubscribe function
+     * @example
+     * ```typescript
+     * store.subscribeTo(
+     *   state => state.connectionStatus,
+     *   status => console.log('Connection:', status)
+     * );
+     * ```
+     */
+    subscribeTo(selector, callback) {
+        let lastValue = selector(this.state);
+        return this.subscribe((state) => {
+            const newValue = selector(state);
+            if (newValue !== lastValue) {
+                lastValue = newValue;
+                callback(newValue);
+            }
+        });
+    }
+    /**
+     * Resets the store to initial state
+     *
+     * @param {Partial<AppState>} [mergeState] - Optional state to merge after reset
+     * @returns {Readonly<AppState>} The reset state
+     */
+    reset(mergeState = {}) {
+        const prevState = this.state;
+        this.state = {
+            ...INITIAL_STATE,
+            ...mergeState,
+            lastUpdated: new Date(),
+        };
+        this.notifyListeners(prevState);
+        return this.getState();
+    }
+    /**
+     * Adds an error to the state
+     *
+     * @param {Omit<AppError, 'id' | 'timestamp' | 'dismissed'>} error - Error details
+     * @returns {Readonly<AppState>} The updated state
+     */
+    addError(error) {
+        const newError = {
+            ...error,
+            id: `err_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`,
+            timestamp: new Date(),
+            dismissed: false,
+        };
+        return this.setState({
+            errors: [...this.state.errors, newError],
+        });
+    }
+    /**
+     * Dismisses an error by ID
+     *
+     * @param {string} errorId - The error ID to dismiss
+     * @returns {Readonly<AppState>} The updated state
+     */
+    dismissError(errorId) {
+        return this.setState({
+            errors: this.state.errors.map((err) => err.id === errorId ? { ...err, dismissed: true } : err),
+        });
+    }
+    /**
+     * Clears all dismissed errors
+     *
+     * @returns {Readonly<AppState>} The updated state
+     */
+    clearDismissedErrors() {
+        return this.setState({
+            errors: this.state.errors.filter((err) => !err.dismissed),
+        });
+    }
+    /**
+     * Adds a message to the conversation
+     *
+     * @param {TypedMessage} message - The message to add
+     * @returns {Readonly<AppState>} The updated state
+     */
+    addMessage(message) {
+        return this.setState({
+            messages: [...this.state.messages, message],
+        });
+    }
+    /**
+     * Clears all messages
+     *
+     * @returns {Readonly<AppState>} The updated state
+     */
+    clearMessages() {
+        return this.setState({ messages: [] });
+    }
+    /**
+     * Sets the user session
+     *
+     * @param {UserSession | null} session - The session or null to logout
+     * @returns {Readonly<AppState>} The updated state
+     */
+    setSession(session) {
+        return this.setState({ session });
+    }
+    /**
+     * Updates user preferences
+     *
+     * @param {Partial<UserPreferences>} prefs - Preference updates
+     * @returns {Readonly<AppState>} The updated state
+     */
+    setPreferences(prefs) {
+        return this.setState({
+            preferences: { ...this.state.preferences, ...prefs },
+        });
+    }
+    /**
+     * Sets the loading state
+     *
+     * @param {boolean} isLoading - Whether loading is active
+     * @param {string} [message] - Optional loading message
+     * @returns {Readonly<AppState>} The updated state
+     */
+    setLoading(isLoading, message) {
+        return this.setState({
+            isLoading,
+            loadingMessage: isLoading ? message ?? null : null,
+        });
+    }
+    /**
+     * Updates view-specific state
+     *
+     * @param {string} view - View identifier
+     * @param {unknown} data - View state data
+     * @returns {Readonly<AppState>} The updated state
+     */
+    setViewState(view, data) {
+        return this.setState({
+            currentView: view,
+            viewState: { ...this.state.viewState, [view]: data },
+        });
+    }
+    notifyListeners(prevState) {
+        queueMicrotask(() => {
+            this.listeners.forEach((listener) => {
+                try {
+                    listener(this.state, prevState);
+                }
+                catch (error) {
+                    console.error('AppStateStore listener error:', error);
+                }
+            });
+        });
+    }
+}
+// Global store instance
+let globalStore = null;
+/**
+ * Gets or creates the global AppStateStore instance
+ *
+ * @returns {AppStateStore} The global store instance
+ */
+export function getGlobalStore() {
+    if (!globalStore) {
+        globalStore = new AppStateStore();
+    }
+    return globalStore;
+}
+/**
+ * Sets the global store instance (useful for testing)
+ *
+ * @param {AppStateStore | null} store - The store instance or null to reset
+ */
+export function setGlobalStore(store) {
+    globalStore = store;
+}
+/**
+ * React hook for accessing the app state store
+ * Provides reactive updates and selector support
+ *
+ * @template T
+ * @param {StateSelector<T>} [selector] - Optional selector function
+ * @returns {T | AppState} The selected state or full state
+ * @example
+ * ```typescript
+ * // Get full state
+ * const state = useAppStateStore();
+ *
+ * // Get specific value
+ * const isLoading = useAppStateStore(state => state.isLoading);
+ *
+ * // Get derived value
+ * const messageCount = useAppStateStore(state => state.messages.length);
+ * ```
+ */
+export function useAppStateStore(selector) {
+    const store = getGlobalStore();
+    return useSyncExternalStore((callback) => store.subscribe(() => callback()), () => {
+        const state = store.getState();
+        return selector ? selector(state) : state;
+    }, () => {
+        const state = store.getState();
+        return selector ? selector(state) : state;
+    });
+}
+/**
+ * React hook for accessing a specific slice of state with optional transformation
+ *
+ * @template T
+ * @param {StateSelector<T>} selector - Function to extract value from state
+ * @param {(left: T, right: T) => boolean} [isEqual] - Custom equality function
+ * @returns {T} The selected value
+ * @example
+ * ```typescript
+ * const userName = useAppStateSelector(state => state.session?.displayName);
+ * ```
+ */
+export function useAppStateSelector(selector, isEqual = Object.is) {
+    const store = getGlobalStore();
+    const [selectedState, setSelectedState] = useState(() => selector(store.getState()));
+    useEffect(() => {
+        let lastSelectedState = selectedState;
+        return store.subscribe((state) => {
+            const newSelectedState = selector(state);
+            if (!isEqual(lastSelectedState, newSelectedState)) {
+                lastSelectedState = newSelectedState;
+                setSelectedState(newSelectedState);
+            }
+        });
+    }, [selector, isEqual, store]);
+    return selectedState;
+}
+/**
+ * React hook for state setters
+ * Returns stable callback functions for common state operations
+ *
+ * @returns {Object} Object containing state setter callbacks
+ * @example
+ * ```typescript
+ * const { setLoading, addMessage, setSession } = useAppStateActions();
+ * ```
+ */
+export function useAppStateActions() {
+    const store = getGlobalStore();
+    const setState = useCallback((updates) => store.setState(updates), [store]);
+    const setLoading = useCallback((isLoading, message) => store.setLoading(isLoading, message), [store]);
+    const addMessage = useCallback((message) => store.addMessage(message), [store]);
+    const setSession = useCallback((session) => store.setSession(session), [store]);
+    const addError = useCallback((error) => store.addError(error), [store]);
+    const dismissError = useCallback((errorId) => store.dismissError(errorId), [store]);
+    const setPreferences = useCallback((prefs) => store.setPreferences(prefs), [store]);
+    const clearMessages = useCallback(() => store.clearMessages(), [store]);
+    return {
+        setState,
+        setLoading,
+        addMessage,
+        setSession,
+        addError,
+        dismissError,
+        setPreferences,
+        clearMessages,
+    };
+}
+// Default export
+export default {
+    AppStateStore,
+    getGlobalStore,
+    setGlobalStore,
+    useAppStateStore,
+    useAppStateSelector,
+    useAppStateActions,
+};