@veams/status-quo 1.7.0 → 1.8.0

package/src/config/status-quo-config.ts

@@ -1,55 +1,91 @@
+/**
+ * Global configuration and utility functions for Status Quo state management.
+ */
+
+// Function signature for comparing state objects to determine if they are distinct.
 export type DistinctComparator<T = unknown> = (previous: T, next: T) => boolean;
 
+// Options for configuring distinct emission behavior in state handlers.
 export type DistinctOptions<T = unknown> = {
+  // Whether distinct updates are enabled.
   enabled?: boolean;
+  // Custom function to compare states for equality.
   comparator?: DistinctComparator<T>;
 };
 
+// Options for configuring Redux DevTools integration for a specific state handler.
 export type DevToolsOptions = {
+  // Whether DevTools integration is enabled for this handler.
   enabled?: boolean;
+  // Namespace for the store in the DevTools window.
   namespace?: string;
 };
 
+// Global options for Redux DevTools integration across all handlers.
 export type GlobalDevToolsOptions = {
+  // Whether DevTools integration is enabled globally.
   enabled?: boolean;
 };
 
+// Main configuration object for the Status Quo system.
 export type StatusQuoConfig<T = unknown> = {
+  // Global DevTools configuration.
   devTools?: GlobalDevToolsOptions;
+  // Global distinct emission configuration.
   distinct?: DistinctOptions<T>;
 };
 
+// Internal representation of resolved distinct options.
 type ResolvedDistinctOptions<T = unknown> = {
+  // Final enabled status for distinct updates.
   enabled: boolean;
+  // Final comparator function to use for equality checks.
   comparator: DistinctComparator<T>;
 };
 
+// Internal representation of resolved DevTools options.
 type ResolvedDevToolsOptions = {
+  // Final enabled status for DevTools.
   enabled: boolean;
 };
 
+// Internal representation of the full resolved configuration.
 type ResolvedStatusQuoConfig = {
+  // Resolved global DevTools configuration.
   devTools: ResolvedDevToolsOptions;
+  // Resolved global distinct emission configuration.
   distinct: ResolvedDistinctOptions;
 };
 
+/**
+ * Default comparator function that uses referential equality (Object.is)
+ * and falls back to JSON stringification for structural equality.
+ */
 function distinctAsJson(previous: unknown, next: unknown) {
+  // Fast path for referential equality.
   if (Object.is(previous, next)) {
     return true;
   }
 
+  // Structural comparison using JSON stringification as a fallback.
   try {
     return JSON.stringify(previous) === JSON.stringify(next);
   } catch {
+    // If stringification fails, assume they are not equal.
     return false;
   }
 }
 
+/**
+ * Creates the default Status Quo configuration.
+ */
 function createDefaultStatusQuoConfig(): ResolvedStatusQuoConfig {
   return {
+    // DevTools integration is disabled by default.
     devTools: {
       enabled: false,
     },
+    // Distinct emission is enabled by default with JSON-based structural equality.
     distinct: {
       enabled: true,
       comparator: distinctAsJson,
@@ -57,13 +93,20 @@ function createDefaultStatusQuoConfig(): ResolvedStatusQuoConfig {
   };
 }
 
+// Global configuration instance, initialized with defaults.
 let statusQuoConfig = createDefaultStatusQuoConfig();
 
+/**
+ * Global setup function to configure Status Quo.
+ */
 export function setupStatusQuo<T = unknown>(config: StatusQuoConfig<T> = {}) {
+  // Merge the provided configuration with the current global config.
   statusQuoConfig = {
+    // Update global DevTools status.
     devTools: {
       enabled: config.devTools?.enabled ?? false,
     },
+    // Update global distinct emission status and comparator.
     distinct: {
       enabled: config.distinct?.enabled ?? true,
       comparator: (config.distinct?.comparator ?? distinctAsJson) as DistinctComparator,
@@ -71,23 +114,39 @@ export function setupStatusQuo<T = unknown>(config: StatusQuoConfig<T> = {}) {
   };
 }
 
+/**
+ * Resolves the final distinct options for a specific state handler.
+ * Combines global configuration with handler-specific overrides.
+ */
 export function resolveDistinctOptions<T>(
+  // Handler-specific distinct options.
   options?: DistinctOptions<T>,
+  // Boolean flag often used to override or determine enabled status.
   useDistinctUntilChanged?: boolean
 ): ResolvedDistinctOptions<T> {
   return {
+    // Determine the enabled status for distinct emissions.
     enabled: options?.enabled ?? useDistinctUntilChanged ?? statusQuoConfig.distinct.enabled,
+    // Determine the comparator function to use.
     comparator: (options?.comparator ??
       statusQuoConfig.distinct.comparator),
   };
 }
 
+/**
+ * Resolves the final DevTools options for a specific state handler.
+ * Combines global configuration with handler-specific overrides.
+ */
 export function resolveDevToolsOptions(options?: DevToolsOptions): ResolvedDevToolsOptions {
   return {
+    // Determine the enabled status for DevTools integration.
     enabled: options?.enabled ?? statusQuoConfig.devTools.enabled,
   };
 }
 
+/**
+ * Returns a copy of the current global configuration.
+ */
 export function getStatusQuoConfig() {
   return {
     devTools: {
@@ -100,7 +159,11 @@ export function getStatusQuoConfig() {
   } as ResolvedStatusQuoConfig;
 }
 
-/** @internal testing helper */
+/**
+ * Resets the Status Quo configuration to its default values.
+ * Useful for ensuring test isolation in unit tests.
+ * @internal testing helper
+ */
 export function resetStatusQuoForTests() {
   statusQuoConfig = createDefaultStatusQuoConfig();
 }

package/src/index.ts

@@ -1,11 +1,19 @@
+/**
+ * Main entry point for the Status Quo state management library.
+ * Exports core functionality for both store and React integration.
+ */
+
+// Import internal setup functions and core state handlers.
 import { setupStatusQuo } from './config/status-quo-config.js';
 import {
   BaseStateHandler,
   makeStateSingleton,
+  NativeStateHandler,
   ObservableStateHandler,
   SignalStateHandler,
 } from './store';
 
+// Import necessary types for external use.
 import type {
   DevToolsOptions,
   GlobalDevToolsOptions,
@@ -16,21 +24,42 @@ import type {
 import type { StateSingleton, StateSingletonOptions } from './store';
 import type { StateSubscriptionHandler } from './types/types.js';
 
+/**
+ * Core state management functions and classes.
+ */
 export {
+  // Abstract base class for all state handlers.
   BaseStateHandler,
+  // Factory function for creating singleton state handlers.
   makeStateSingleton,
+  // Lightweight state handler using plain JavaScript.
+  NativeStateHandler,
+  // State handler powered by RxJS BehaviorSubjects.
   ObservableStateHandler,
+  // Global configuration function for Status Quo.
   setupStatusQuo,
+  // State handler powered by Preact Signals.
   SignalStateHandler,
 };
 
+/**
+ * Type definitions for public API.
+ */
 export type {
+  // Options for Redux DevTools integration.
   DevToolsOptions,
+  // Global options for Redux DevTools.
   GlobalDevToolsOptions,
+  // Function signature for state equality comparisons.
   DistinctComparator,
+  // Options for configuring distinct updates.
   DistinctOptions,
+  // Interface representing a singleton state handler.
   StateSingleton,
+  // Options for configuring state singleton instances.
   StateSingletonOptions,
+  // Interface representing a standard state subscription handler.
   StateSubscriptionHandler,
+  // Main configuration object for the Status Quo system.
   StatusQuoConfig,
 };

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

@@ -6,7 +6,7 @@ import {
   useProvidedStateActions,
   useProvidedStateHandler,
   useProvidedStateSubscription,
-} from '../state-provider.js';
+} from '../index.js';
 
 import type { StateSubscriptionHandler } from '../../../types/types.js';
 
@@ -279,7 +279,7 @@ describe('StateProvider', () => {
       act(() => {
         root.render(<MissingProviderConsumer />);
       });
-    }).toThrow('No StateProvider instance found in the current React tree.');
+    }).toThrow('useProvidedStateHandler must be used within a StateProvider');
 
     consoleErrorSpy.mockRestore();
   });

package/src/react/hooks/index.ts

@@ -1,11 +1,16 @@
-export { useStateActions } from './state-actions.js';
+/**
+ * Export available hooks for React components.
+ */
+
+// Export hook to access the actions of a state handler.
+export { useProvidedStateActions, useStateActions } from './state-actions.js';
+// Export hook to create and manage a state handler within a component.
 export { useStateFactory } from './state-factory.js';
+// Export hook to manage a state handler's lifecycle within a component's reference.
 export { useStateHandler } from './state-handler.js';
-export {
-  StateProvider,
-  useProvidedStateActions,
-  useProvidedStateHandler,
-  useProvidedStateSubscription,
-} from './state-provider.js';
+// Export hook and component to use a state handler through React Context.
+export { StateProvider, useProvidedStateHandler } from './state-provider.js';
+// Export hook to use a singleton state handler.
 export { useStateSingleton } from './state-singleton.js';
-export { useStateSubscription } from './state-subscription.js';
+// Export hook to subscribe to a state handler and receive its state updates.
+export { useProvidedStateSubscription, useStateSubscription } from './state-subscription.js';

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);
 }