@veams/status-quo 1.6.0 → 1.8.0

package/src/react/hooks/state-actions.tsx

@@ -1,7 +1,28 @@
+/**
+ * Utility hook for accessing actions from a state handler instance.
+ */
 import { useMemo } from 'react';
 
 import type { StateSubscriptionHandler } from '../../types/types.js';
+import { useProvidedStateHandler } from './state-provider.js';
 
-export function useStateActions<V, A>(stateSubscriptionHandler: StateSubscriptionHandler<V, A>) {
-  return useMemo(() => stateSubscriptionHandler.getActions(), [stateSubscriptionHandler]);
+/**
+ * Returns the actions of a state handler instance.
+ * memoized based on the state handler instance itself.
+ */
+export function useStateActions<V, A>(stateHandler: StateSubscriptionHandler<V, A>): A {
+  // Access and memoize the actions from the state handler.
+  // This ensures the action object remains referentially stable as long as the state handler is the same.
+  const actions = useMemo(() => stateHandler.getActions(), [stateHandler]);
+
+  // Return the set of actions.
+  return actions;
+}
+
+/**
+ * Returns the actions of the state handler provided by the nearest StateProvider.
+ */
+export function useProvidedStateActions<V, A>(): A {
+  const stateHandler = useProvidedStateHandler<V, A>();
+  return useStateActions(stateHandler);
 }

package/src/react/hooks/state-factory.tsx

@@ -1,42 +1,76 @@
+/**
+ * Utility hook for creating and subscribing to a state handler within a component.
+ * Combines creation and subscription logic in a single call.
+ */
 import { useStateHandler } from './state-handler.js';
 import { useStateSubscription } from './state-subscription.js';
 
 import type { StateSubscriptionHandler } from '../../types/types.js';
 
+/**
+ * Type signatures for selector and equality functions.
+ */
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
 
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = <State,>(state: State) => state;
 
+/**
+ * Factory hook to create and subscribe to a state handler.
+ * Manages the handler instance using useStateHandler and its subscription with useStateSubscription.
+ */
 export function useStateFactory<V, A, P extends unknown[]>(
+  // Function to create a new state handler instance.
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,
+  // Parameters to pass to the factory function.
   params?: P
 ): [V, A];
 export function useStateFactory<V, A, P extends unknown[], Sel>(
+  // Function to create a new state handler instance.
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,
+  // Selector function to derive a specific value from the state.
   selector: StateSelector<V, Sel>,
+  // Parameters to pass to the factory function.
   params?: P
 ): [Sel, A];
 export function useStateFactory<V, A, P extends unknown[], Sel>(
+  // Function to create a new state handler instance.
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,
+  // Selector function to derive a specific value from the state.
   selector: StateSelector<V, Sel>,
+  // Optional equality function to compare selected values.
   isEqual?: EqualityFn<Sel>,
+  // Parameters to pass to the factory function.
   params?: P
 ): [Sel, A];
 export function useStateFactory<V, A, P extends unknown[], Sel = V>(
+  // Implementation of the overloaded useStateFactory hook.
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,
+  // Mixed argument: can be a selector or params array.
   selectorOrParams: StateSelector<V, Sel> | P = [] as unknown as P,
+  // Mixed argument: can be an equality function or params array.
   isEqualOrParams: EqualityFn<Sel> | P = Object.is as EqualityFn<Sel>,
+  // Optional params array.
   params: P = [] as unknown as P
 ) {
+  // Determine whether a selector was provided.
   const hasSelector = typeof selectorOrParams === 'function';
+  // Fallback to identity selector if none is provided.
   const selector = (hasSelector ? selectorOrParams : identitySelector) as StateSelector<V, Sel>;
+  // Determine whether a custom equality function was provided.
   const hasCustomEquality = hasSelector && typeof isEqualOrParams === 'function';
+  // Fallback to default equality check (Object.is).
   const isEqual = (hasCustomEquality ? isEqualOrParams : Object.is);
+  // Resolve the parameters for the state handler factory.
   const stateFactoryParams = (
     hasSelector ? (hasCustomEquality ? params : isEqualOrParams) : selectorOrParams
   ) as P;
+  // Create and persist the state handler instance using its factory and parameters.
   const stateHandler = useStateHandler(stateFactoryFunction, stateFactoryParams);
 
+  // Subscribe to the state handler and return the selected state and actions.
   return useStateSubscription(stateHandler, selector, isEqual);
 }

package/src/react/hooks/state-handler.tsx

@@ -1,16 +1,31 @@
+/**
+ * Utility hook for managing the lifecycle of a state handler instance.
+ * Ensures the instance is created once and persisted across component re-renders.
+ */
 import { useRef } from 'react';
 
 import type { StateSubscriptionHandler } from '../../types/types.js';
 
+/**
+ * Returns a stable state handler instance based on a factory function.
+ * Uses a ref to ensure the factory function is only executed during initial render.
+ */
 export function useStateHandler<V, A, P extends unknown[]>(
+  // Function to create a new state handler instance.
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,
+  // Parameters to pass to the factory function.
   params: P = [] as unknown as P
 ) {
+  // Use a ref to store the state handler instance.
+  // This prevents the state handler from being recreated on every re-render.
   const stateHandlerRef = useRef<StateSubscriptionHandler<V, A> | null>(null);
 
+  // If the ref is currently null, we create the instance for the first time.
   if (!stateHandlerRef.current) {
+    // Invoke the factory function with the provided parameters.
     stateHandlerRef.current = stateFactoryFunction(...params);
   }
 
+  // Return the stable state handler instance.
   return stateHandlerRef.current;
 }

package/src/react/hooks/state-provider.tsx

@@ -1,56 +1,52 @@
+/**
+ * Utility hook for providing a state handler through React Context.
+ * Allows components deep in the component tree to access a common state handler instance.
+ */
 import React, { createContext, useContext } from 'react';
 
-import { useStateActions } from './state-actions.js';
-import { useStateSubscription } from './state-subscription.js';
-
-import type { PropsWithChildren } from 'react';
 import type { StateSubscriptionHandler } from '../../types/types.js';
 
-type StateSelector<State, SelectedState> = (state: State) => SelectedState;
-type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
-type SharedStateHandler = StateSubscriptionHandler<unknown, unknown>;
-
-const StateProviderContext = createContext<SharedStateHandler | null>(null);
-const identitySelector = <State,>(state: State) => state;
-
-export type StateProviderProps<V, A> = PropsWithChildren<{
+/**
+ * Interface for the state provider component props.
+ */
+interface StateProviderProps<V, A> {
+  // Children components that will have access to the state handler.
+  children: React.ReactNode;
+  // The state handler instance to be provided to the component tree.
   instance: StateSubscriptionHandler<V, A>;
-}>;
-
-export function useProvidedStateHandler<V, A>() {
-  const stateHandler = useContext(StateProviderContext);
-
-  if (!stateHandler) {
-    throw new Error('No StateProvider instance found in the current React tree.');
-  }
-
-  return stateHandler as StateSubscriptionHandler<V, A>;
 }
 
+/**
+ * Creates a React Context for storing and providing the state handler instance.
+ * Initialized with null as there is no default state handler.
+ */
+const StateContext = createContext<StateSubscriptionHandler<unknown, unknown> | null>(null);
+
+/**
+ * Provides a state handler instance to its descendant components using React Context.
+ */
 export function StateProvider<V, A>({ children, instance }: StateProviderProps<V, A>) {
+  // Use a context provider to share the state handler instance.
   return (
-    <StateProviderContext.Provider value={instance as SharedStateHandler}>
+    <StateContext.Provider value={instance as StateSubscriptionHandler<unknown, unknown>}>
       {children}
-    </StateProviderContext.Provider>
+    </StateContext.Provider>
   );
 }
 
-export function useProvidedStateActions<V, A>() {
-  const stateHandler = useProvidedStateHandler<V, A>();
-
-  return useStateActions(stateHandler);
-}
+/**
+ * Custom hook to access the state handler provided by the StateProvider.
+ * Throws an error if the hook is used outside of a StateProvider.
+ */
+export function useProvidedStateHandler<V, A>(): StateSubscriptionHandler<V, A> {
+  // Retrieve the state handler from the nearest context provider.
+  const stateHandler = useContext(StateContext);
 
-export function useProvidedStateSubscription<V, A>(): [V, A];
-export function useProvidedStateSubscription<V, A, Sel>(
-  selector: StateSelector<V, Sel>,
-  isEqual?: EqualityFn<Sel>
-): [Sel, A];
-export function useProvidedStateSubscription<V, A, Sel = V>(
-  selector: StateSelector<V, Sel> = identitySelector as StateSelector<V, Sel>,
-  isEqual: EqualityFn<Sel> = Object.is
-) {
-  const stateHandler = useProvidedStateHandler<V, A>();
+  // If no state handler is found, it means the hook is being used incorrectly.
+  if (!stateHandler) {
+    throw new Error('useProvidedStateHandler must be used within a StateProvider');
+  }
 
-  return useStateSubscription(stateHandler, selector, isEqual);
+  // Cast and return the state handler instance.
+  return stateHandler as StateSubscriptionHandler<V, A>;
 }

package/src/react/hooks/state-singleton.tsx

@@ -1,24 +1,54 @@
+/**
+ * Utility hook for subscribing to a state singleton within a component.
+ */
 import { useStateSubscription } from './state-subscription.js';
 
 import type { StateSingleton } from '../../store/state-singleton.js';
 
+/**
+ * Type signatures for selector and equality functions.
+ */
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
 
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = <State,>(state: State) => state;
 
-export function useStateSingleton<V, A>(stateSingleton: StateSingleton<V, A>): [V, A];
+/**
+ * Singleton hook to subscribe to a state singleton.
+ */
+export function useStateSingleton<V, A>(
+  // The state singleton instance to subscribe to.
+  singleton: StateSingleton<V, A>
+): [V, A];
 export function useStateSingleton<V, A, Sel>(
-  stateSingleton: StateSingleton<V, A>,
+  // The state singleton instance to subscribe to.
+  singleton: StateSingleton<V, A>,
+  // Selector function to derive a specific value from the state.
   selector: StateSelector<V, Sel>,
+  // Optional equality function to compare selected values.
   isEqual?: EqualityFn<Sel>
 ): [Sel, A];
 export function useStateSingleton<V, A, Sel = V>(
-  stateSingleton: StateSingleton<V, A>,
-  selector: StateSelector<V, Sel> = identitySelector as StateSelector<V, Sel>,
-  isEqual: EqualityFn<Sel> = Object.is
+  // Implementation of the overloaded useStateSingleton hook.
+  singleton: StateSingleton<V, A>,
+  // Mixed argument: can be a selector or equality function.
+  selectorOrIsEqual: StateSelector<V, Sel> | EqualityFn<Sel> = identitySelector as StateSelector<
+    V,
+    Sel
+  >,
+  // Mixed argument: can be an equality function or undefined.
+  isEqual: EqualityFn<Sel> = Object.is as EqualityFn<Sel>
 ) {
-  const [state, actions] = useStateSubscription(stateSingleton, selector, isEqual);
+  // Determine whether a selector was provided as the first optional argument.
+  const hasSelector = typeof selectorOrIsEqual === 'function' && selectorOrIsEqual.length === 1;
+  // Fallback to identity selector if none is provided.
+  const selector = (hasSelector ? selectorOrIsEqual : identitySelector) as StateSelector<V, Sel>;
+  // Resolve the equality function to use.
+  const equalityFn = (hasSelector ? isEqual : selectorOrIsEqual) as EqualityFn<Sel>;
 
-  return [state, actions] as [Sel, A];
+  // Subscribe to the singleton state handler and return the selected state and actions.
+  return useStateSubscription(singleton, selector, equalityFn);
 }

package/src/react/hooks/state-subscription-selector.tsx

@@ -1,3 +1,7 @@
+/**
+ * Utility hook for subscribing to a state handler and selecting a specific value from the state.
+ * Uses useSyncExternalStore to ensure consistent state reads and avoid unnecessary re-renders.
+ */
 import { useCallback, useRef, useSyncExternalStore } from 'react';
 
 import { createSelectorCache, selectWithCache } from '../../utils/selector-cache.js';
@@ -5,24 +9,67 @@ import { createSelectorCache, selectWithCache } from '../../utils/selector-cache
 import type { StateSubscriptionHandler } from '../../types/types.js';
 import type { EqualityFn, Selector } from '../../utils/selector-cache.js';
 
+/**
+ * Type signature for listener functions.
+ */
 type Listener = () => void;
+
+/**
+ * Represents a state subscription handler with unknown state and actions.
+ */
 type SharedStateSubscriptionHandler = StateSubscriptionHandler<unknown, unknown>;
+
+/**
+ * Tracks the reference count and deferred destruction status of a state handler.
+ */
 type DeferredDestroy = {
+  // Number of active consumers of the state handler.
   refCount: number;
+  // ID of the timeout for deferred destruction.
   timeoutId: ReturnType<typeof setTimeout> | null;
 };
 
+/**
+ * Cache entry for a selected state snapshot.
+ */
+type SnapshotCacheEntry<Source, Selected> = {
+  // The selected value derived from the source snapshot.
+  selectedSnapshot: Selected;
+  // The source snapshot from which the value was selected.
+  sourceSnapshot: Source;
+  // A version number to track state changes.
+  version: number;
+};
+
+/**
+ * Cache entry for a selected server state snapshot (SSR).
+ */
+type ServerSnapshotCacheEntry<Source, Selected> = {
+  // The selected value derived from the source snapshot.
+  selectedSnapshot: Selected;
+  // The source snapshot from which the value was selected.
+  sourceSnapshot: Source;
+};
+
+// Global map to track deferred destruction status for each state handler instance.
 const deferredDestroyMap = new WeakMap<SharedStateSubscriptionHandler, DeferredDestroy>();
 
+/**
+ * Returns the deferred destruction status for a given state handler instance.
+ * Initializes the status if it does not already exist.
+ */
 function getDeferredDestroyState(
   stateSubscriptionHandler: SharedStateSubscriptionHandler
 ): DeferredDestroy {
+  // Retrieve the existing status from the map.
   const existingState = deferredDestroyMap.get(stateSubscriptionHandler);
 
+  // If status already exists, return it.
   if (existingState) {
     return existingState;
   }
 
+  // Create and store a new status for the handler.
   const nextState: DeferredDestroy = {
     refCount: 0,
     timeoutId: null,
@@ -33,65 +80,105 @@ function getDeferredDestroyState(
   return nextState;
 }
 
+/**
+ * Custom hook to select and subscribe to a specific piece of state from a handler.
+ * Efficiently manages subscriptions and selector results.
+ */
 export function useStateSubscriptionSelector<V, A, Sel>(
+  // The state handler instance to subscribe to.
   stateSubscriptionHandler: StateSubscriptionHandler<V, A>,
+  // Selector function to derive a value from the state.
   selector: Selector<V, Sel>,
+  // Equality function to compare selected values for changes.
   isEqual: EqualityFn<Sel> = Object.is,
+  // Whether to automatically destroy the handler instance on component unmount.
   destroyOnCleanup = true
 ) {
+  // Cache for the selector results to ensure referential stability.
   const selectorCacheRef = useRef<ReturnType<typeof createSelectorCache<Sel>> | null>(null);
+  // Tracks store notifications so getSnapshot can reuse the same selected value within one store version.
+  const snapshotVersionRef = useRef(0);
+  // Client-side cache for selected snapshots per source snapshot/version pair.
+  const snapshotCacheRef = useRef<SnapshotCacheEntry<V, Sel> | null>(null);
+  // Separate cache for the server snapshot function used by SSR/hydration paths.
+  const serverSnapshotCacheRef = useRef<ServerSnapshotCacheEntry<V, Sel> | null>(null);
 
+  // Initialize the selector cache if it doesn't already exist.
   if (!selectorCacheRef.current) {
     selectorCacheRef.current = createSelectorCache<Sel>();
   }
 
   const selectorCache = selectorCacheRef.current;
 
+  // Subscription function to be used by useSyncExternalStore.
   const subscribe = useCallback(
     (listener: Listener) => {
+      // Access the deferred destruction status for this handler.
       const sharedStateSubscriptionHandler =
         stateSubscriptionHandler as unknown as SharedStateSubscriptionHandler;
       const deferredDestroyState = getDeferredDestroyState(sharedStateSubscriptionHandler);
+      // Increment the consumer reference count.
       deferredDestroyState.refCount += 1;
 
+      // If a pending destruction timeout is scheduled, cancel it.
       if (deferredDestroyState.timeoutId) {
         clearTimeout(deferredDestroyState.timeoutId);
         deferredDestroyState.timeoutId = null;
       }
 
-      const unsubscribe = stateSubscriptionHandler.subscribe(listener);
+      // Subscribe to the state handler.
+      const unsubscribe = stateSubscriptionHandler.subscribe(() => {
+        // Invalidate the selected snapshot cache before notifying React of a change.
+        snapshotVersionRef.current += 1;
+        snapshotCacheRef.current = null;
+        // Notify React to re-trigger a getSnapshot call.
+        listener();
+      });
 
+      // Return an unsubscribe function to be called by React.
       return () => {
+        // Execute the handler's unsubscribe method.
         unsubscribe();
 
+        // If automatic cleanup is disabled, stop here.
         if (!destroyOnCleanup) {
           return;
         }
 
+        // Retrieve the current destruction status.
         const activeDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
 
+        // If no status is found, stop here.
         if (!activeDeferredDestroyState) {
           return;
         }
 
+        // Decrement the consumer reference count.
         activeDeferredDestroyState.refCount -= 1;
 
+        // If there are still active consumers, do not destroy the handler.
         if (activeDeferredDestroyState.refCount > 0) {
           return;
         }
 
+        // Reset the reference count to zero.
         activeDeferredDestroyState.refCount = 0;
+        // Schedule deferred destruction to allow for potential immediate re-subscriptions.
         activeDeferredDestroyState.timeoutId = setTimeout(() => {
+          // Check if the handler still has no consumers after the timeout.
           const pendingDeferredDestroyState = deferredDestroyMap.get(
             sharedStateSubscriptionHandler
           );
 
+          // If consumers have reappeared, do not destroy the handler.
           if (!pendingDeferredDestroyState || pendingDeferredDestroyState.refCount > 0) {
             return;
           }
 
+          // Clear the pending timeout and destroy the state handler.
           pendingDeferredDestroyState.timeoutId = null;
           stateSubscriptionHandler.destroy();
+          // Remove the status from the global map.
           deferredDestroyMap.delete(sharedStateSubscriptionHandler);
         }, 0);
       };
@@ -99,6 +186,7 @@ export function useStateSubscriptionSelector<V, A, Sel>(
     [destroyOnCleanup, stateSubscriptionHandler]
   );
 
+  // Helper to execute selection using the cache.
   const selectSnapshot = useCallback(
     (snapshot: V) => {
       return selectWithCache(selectorCache, snapshot, selector, isEqual).value;
@@ -106,15 +194,75 @@ export function useStateSubscriptionSelector<V, A, Sel>(
     [isEqual, selector, selectorCache]
   );
 
+  // Reference to track changes in selection strategy.
+  const selectorCacheControlRef = useRef(selectSnapshot);
+
+  // If the selector or equality function changes, clear all caches.
+  if (selectorCacheControlRef.current !== selectSnapshot) {
+    selectorCacheControlRef.current = selectSnapshot;
+    snapshotVersionRef.current = 0;
+    snapshotCacheRef.current = null;
+    serverSnapshotCacheRef.current = null;
+  }
+
+  // Snapshot retrieval function to be used by useSyncExternalStore.
   const getSnapshot = useCallback(
-    () => selectSnapshot(stateSubscriptionHandler.getSnapshot()),
+    () => {
+      // Retrieve the current source state from the handler.
+      const sourceSnapshot = stateSubscriptionHandler.getSnapshot();
+      // Access the current version and cached value.
+      const version = snapshotVersionRef.current;
+      const cachedSnapshot = snapshotCacheRef.current;
+
+      // If the cached selection is still valid for this version and source state, return it.
+      if (
+        cachedSnapshot &&
+        cachedSnapshot.version === version &&
+        Object.is(cachedSnapshot.sourceSnapshot, sourceSnapshot)
+      ) {
+        return cachedSnapshot.selectedSnapshot;
+      }
+
+      // Compute a new selection and update the cache.
+      const selectedSnapshot = selectSnapshot(sourceSnapshot);
+      snapshotCacheRef.current = {
+        selectedSnapshot,
+        sourceSnapshot,
+        version,
+      };
+
+      // Return the new selection.
+      return selectedSnapshot;
+    },
     [selectSnapshot, stateSubscriptionHandler]
   );
 
+  // Server snapshot retrieval function to be used for SSR/hydration.
   const getServerSnapshot = useCallback(
-    () => selectSnapshot(stateSubscriptionHandler.getInitialState()),
+    () => {
+      // Retrieve the initial source state from the handler.
+      const sourceSnapshot = stateSubscriptionHandler.getInitialState();
+      // Access the current cached server snapshot.
+      const cachedSnapshot = serverSnapshotCacheRef.current;
+
+      // If the cached server selection is still valid for the initial state, return it.
+      if (cachedSnapshot && Object.is(cachedSnapshot.sourceSnapshot, sourceSnapshot)) {
+        return cachedSnapshot.selectedSnapshot;
+      }
+
+      // Compute a new server selection and update its cache.
+      const selectedSnapshot = selectSnapshot(sourceSnapshot);
+      serverSnapshotCacheRef.current = {
+        selectedSnapshot,
+        sourceSnapshot,
+      };
+
+      // Return the initial selection result.
+      return selectedSnapshot;
+    },
     [selectSnapshot, stateSubscriptionHandler]
   );
 
+  // Use the useSyncExternalStore hook to integrate the state with React's rendering lifecycle.
   return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
 }