@veams/status-quo 1.7.0 → 1.8.0

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,33 +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,
@@ -42,78 +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. This keeps useSyncExternalStore reads referentially stable.
+  // 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;
       }
 
+      // Subscribe to the state handler.
       const unsubscribe = stateSubscriptionHandler.subscribe(() => {
-        // Invalidate the selected snapshot cache before notifying React.
-        // Any next getSnapshot call should recompute from the new store state.
+        // 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);
       };
@@ -121,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;
@@ -128,31 +194,36 @@ 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) {
-    // Selector/equality changes define a new selection strategy, so clear all caches.
     selectorCacheControlRef.current = selectSnapshot;
     snapshotVersionRef.current = 0;
     snapshotCacheRef.current = null;
     serverSnapshotCacheRef.current = null;
   }
 
+  // Snapshot retrieval function to be used by useSyncExternalStore.
   const getSnapshot = useCallback(
     () => {
+      // 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)
       ) {
-        // Same source snapshot in the same store version: return the exact same selected reference.
         return cachedSnapshot.selectedSnapshot;
       }
 
+      // Compute a new selection and update the cache.
       const selectedSnapshot = selectSnapshot(sourceSnapshot);
       snapshotCacheRef.current = {
         selectedSnapshot,
@@ -160,31 +231,38 @@ export function useStateSubscriptionSelector<V, A, Sel>(
         version,
       };
 
+      // Return the new selection.
       return selectedSnapshot;
     },
     [selectSnapshot, stateSubscriptionHandler]
   );
 
+  // Server snapshot retrieval function to be used for SSR/hydration.
   const getServerSnapshot = useCallback(
     () => {
+      // 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)) {
-        // Keep server snapshot reads stable for hydration by reusing cached selection.
         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);
 }

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

@@ -1,3 +1,7 @@
+/**
+ * Utility hook for subscribing to a state handler or a state singleton.
+ * Manages the lifecycle and reference counting for shared state handler instances.
+ */
 import { useEffect, useMemo } from 'react';
 
 import { useStateActions } from './state-actions.js';
@@ -5,28 +9,57 @@ import { useStateSubscriptionSelector } from './state-subscription-selector.js';
 
 import type { StateSingleton } from '../../store/state-singleton.js';
 import type { StateSubscriptionHandler } from '../../types/types.js';
+import { useProvidedStateHandler } from './state-provider.js';
 
+/**
+ * Type signatures for selector and equality functions.
+ */
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
+
+/**
+ * Interface representing a state singleton with optional internal management methods.
+ */
 type ManagedSingleton = StateSingleton<unknown, unknown> & {
+  // Method to manually destroy the singleton instance.
   destroyInstance?: () => void;
+  // Flag indicating if the instance should be destroyed when no more consumers are active.
   destroyOnNoConsumers?: boolean;
 };
+
+/**
+ * Alias for a standard state handler instance.
+ */
 type SharedStateHandler = StateSubscriptionHandler<unknown, unknown>;
 
+/**
+ * Global map to track reference counts for singleton state handler instances.
+ * Used to determine when it's safe to destroy a shared singleton.
+ */
 const singletonReferences = new WeakMap<
   StateSingleton<unknown, unknown>,
   { count: number; stateHandler: SharedStateHandler }
 >();
 
+/**
+ * Default identity selector returns the whole state.
+ */
 const identitySelector = <State,>(state: State) => state;
 
+/**
+ * Type guard function to check if a source is a StateSingleton.
+ */
 function isStateSingleton<V, A>(
   source: StateSubscriptionHandler<V, A> | StateSingleton<V, A>
 ): source is StateSingleton<V, A> {
+  // Check for the presence of the getInstance method.
   return 'getInstance' in source;
 }
 
+/**
+ * Custom hook to subscribe to a state handler or singleton and receive its state and actions.
+ * Correctly manages shared instances and reference counting.
+ */
 export function useStateSubscription<V, A>(source: StateSubscriptionHandler<V, A>): [V, A];
 export function useStateSubscription<V, A, Sel>(
   source: StateSubscriptionHandler<V, A>,
@@ -40,66 +73,108 @@ export function useStateSubscription<V, A, Sel>(
   isEqual?: EqualityFn<Sel>
 ): [Sel, A];
 export function useStateSubscription<V, A, Sel = V>(
+  // Implementation of the overloaded useStateSubscription hook.
   source: StateSubscriptionHandler<V, A> | StateSingleton<V, A>,
+  // Selector function to derive a specific value from the state.
   selector: StateSelector<V, Sel> = identitySelector as StateSelector<V, Sel>,
+  // Optional equality function to compare selected values for changes.
   isEqual: EqualityFn<Sel> = Object.is
 ) {
+  // Determine if the source is a singleton instance or a direct state handler.
   const singletonSource = isStateSingleton(source) ? source : null;
+  // Resolve the final state subscription handler instance to use.
   const stateSubscriptionHandler = useMemo<StateSubscriptionHandler<V, A>>(() => {
+    // If it's a singleton, access its managed instance.
     if (singletonSource) {
       return singletonSource.getInstance();
     }
 
+    // Otherwise, return the source handler instance directly.
     return source as StateSubscriptionHandler<V, A>;
   }, [singletonSource, source]);
 
+  // Use an effect to manage the lifecycle and reference count of singleton instances.
   useEffect(() => {
+    // If the source is not a singleton, no lifecycle management is needed here.
     if (!singletonSource) {
       return undefined;
     }
 
+    // Cast the source to access management properties and retrieve the current reference.
     const singleton = singletonSource as ManagedSingleton;
     const sharedStateHandler = stateSubscriptionHandler as SharedStateHandler;
     const singletonReference = singletonReferences.get(singleton);
 
+    // Update the reference count for the singleton instance.
     if (!singletonReference || singletonReference.stateHandler !== sharedStateHandler) {
+      // Initialize the count if it doesn't already exist or has changed.
       singletonReferences.set(singleton, { count: 1, stateHandler: sharedStateHandler });
     } else {
+      // Increment the consumer count.
       singletonReference.count += 1;
     }
 
+    // Return an effect cleanup function to decrement the count when the component unmounts.
     return () => {
+      // Access the active reference for the singleton.
       const activeReference = singletonReferences.get(singleton);
 
+      // If no active reference is found, do nothing.
       if (!activeReference || activeReference.stateHandler !== sharedStateHandler) {
         return;
       }
 
+      // Decrement the consumer count.
       activeReference.count -= 1;
 
+      // If there are still active consumers, do not destroy the instance.
       if (activeReference.count <= 0) {
+        // Remove the reference from the map when the count reaches zero.
         singletonReferences.delete(singleton);
+
+        // Only proceed with destruction if destroyOnNoConsumers is explicitly enabled.
         if (singleton.destroyOnNoConsumers !== true) {
           return;
         }
 
+        // Use the singleton's internal destroy method if available.
         if (singleton.destroyInstance) {
           singleton.destroyInstance();
           return;
         }
 
+        // Otherwise, invoke the handler's destroy method directly.
         stateSubscriptionHandler.destroy();
       }
     };
   }, [singletonSource, stateSubscriptionHandler]);
 
+  // Select and subscribe to the state value using the useStateSubscriptionSelector hook.
   const state = useStateSubscriptionSelector(
     stateSubscriptionHandler,
     selector,
     isEqual,
     !singletonSource
   );
+  // Retrieve the set of actions from the state handler.
   const actions = useStateActions(stateSubscriptionHandler);
 
+  // Return the selected state and its actions as a tuple.
   return [state, actions] as [Sel, A];
 }
+
+/**
+ * Custom hook to subscribe to the state handler provided by the nearest StateProvider.
+ */
+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>();
+  return useStateSubscription(stateHandler, selector, isEqual);
+}

package/src/react/index.ts

@@ -1 +1,16 @@
-export * from './hooks/index.js';
+/**
+ * Export core React hooks and components for Status Quo.
+ */
+
+// Export hooks and components to manage state and actions.
+export {
+  StateProvider,
+  useProvidedStateActions,
+  useProvidedStateHandler,
+  useProvidedStateSubscription,
+  useStateActions,
+  useStateFactory,
+  useStateHandler,
+  useStateSingleton,
+  useStateSubscription,
+} from './hooks/index.js';