@veams/status-quo 1.7.0 → 1.8.0

package/src/store/native-state-handler.ts

@@ -0,0 +1,98 @@
+/**
+ * Import internal configuration and the abstract base state handler.
+ */
+import { resolveDistinctOptions } from '../config/status-quo-config.js';
+import { BaseStateHandler } from './base-state-handler.js';
+
+/**
+ * Import necessary types for DevTools and distinct update options.
+ */
+import type { DevToolsOptions, DistinctOptions } from '../config/status-quo-config.js';
+
+/**
+ * Props for configuring the NativeStateHandler instance.
+ */
+type NativeStateHandlerProps<S> = {
+  // The initial value for the state.
+  initialState: S;
+  // Optional configuration for DevTools and distinct update behaviors.
+  options?: {
+    devTools?: DevToolsOptions;
+    distinct?: DistinctOptions<S>;
+    useDistinctUntilChanged?: boolean;
+  };
+};
+
+/**
+ * NativeStateHandler: A lightweight state handler using plain JavaScript.
+ * Ideal for minimizing dependencies when neither RxJS nor Signals are required.
+ */
+export abstract class NativeStateHandler<S, A> extends BaseStateHandler<S, A> {
+  // The actual state value stored in memory.
+  private state: S;
+  // A collection of active listeners to notify when the state changes.
+  private readonly listeners: Set<(value: S) => void> = new Set();
+  // Configuration to determine if and how state changes should trigger notifications.
+  private readonly distinctOptions: ReturnType<typeof resolveDistinctOptions<S>>;
+
+  /**
+   * Initializes the native state handler with given state and configuration.
+   */
+  protected constructor({ initialState, options }: NativeStateHandlerProps<S>) {
+    // Pass the initial state to the base handler.
+    super(initialState);
+    // Set the initial internal state.
+    this.state = initialState;
+    // Resolve the final distinct options based on provided configuration.
+    this.distinctOptions = resolveDistinctOptions(
+      options?.distinct,
+      options?.useDistinctUntilChanged
+    );
+    // Initialize Redux DevTools integration.
+    this.initDevTools(options?.devTools);
+  }
+
+  /**
+   * Internal implementation of getting the state value.
+   */
+  protected getStateValue() {
+    return this.state;
+  }
+
+  /**
+   * Internal implementation of updating the state value.
+   */
+  protected setStateValue(nextState: S) {
+    // Store the previous state to compare against the new state.
+    const previousState = this.state;
+    // Update the internal state storage.
+    this.state = nextState;
+
+    // If distinct mode is enabled and the state hasn't effectively changed, stop here.
+    if (this.distinctOptions.enabled && this.distinctOptions.comparator(previousState, nextState)) {
+      return;
+    }
+
+    // Notify all active listeners of the state update.
+    this.listeners.forEach((listener) => listener(nextState));
+  }
+
+  /**
+   * Subscribes a listener function to state changes.
+   * Overloaded to handle both void and state-receiving listeners.
+   */
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: S) => void): () => void;
+  subscribe(listener: (value: S) => void) {
+    // Register the listener to the active set.
+    this.listeners.add(listener);
+
+    // Call the listener immediately with the current state to ensure initial consistency.
+    listener(this.state);
+
+    // Return an unsubscribe function to remove the listener from the set.
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+}

package/src/store/observable-state-handler.ts

@@ -1,13 +1,27 @@
+/**
+ * Import RxJS components for reactive state handling.
+ */
 import { BehaviorSubject, distinctUntilChanged, distinctUntilKeyChanged, map } from 'rxjs';
 
+/**
+ * Import internal configuration and the abstract base state handler.
+ */
 import { resolveDistinctOptions } from '../config/status-quo-config.js';
 import { BaseStateHandler } from './base-state-handler.js';
 
+/**
+ * Import necessary types for DevTools, distinct update options, and RxJS Observable.
+ */
 import type { DevToolsOptions, DistinctOptions } from '../config/status-quo-config.js';
 import type { Observable } from 'rxjs';
 
+/**
+ * Props for configuring the ObservableStateHandler instance.
+ */
 type ObservableStateHandlerProps<S> = {
+  // The initial value for the state.
   initialState: S;
+  // Optional configuration for DevTools and distinct update behaviors.
   options?: {
     devTools?: DevToolsOptions;
     distinct?: DistinctOptions<S>;
@@ -15,57 +29,100 @@ type ObservableStateHandlerProps<S> = {
   };
 };
 
+/**
+ * Options for configuring state-related observables.
+ */
 type StateObservableOptions = { useDistinctUntilChanged?: boolean };
 
+/**
+ * ObservableStateHandler: A state handler built on top of RxJS BehaviorSubject.
+ * Provides powerful reactive patterns and integration with RxJS pipelines.
+ */
 export abstract class ObservableStateHandler<S, A> extends BaseStateHandler<S, A> {
+  // Internal BehaviorSubject to manage the state and provide current values to new subscribers.
   private readonly state$: BehaviorSubject<S>;
+  // Configuration to determine if and how state changes should trigger notifications.
   private readonly distinctOptions: ReturnType<typeof resolveDistinctOptions<S>>;
 
+  /**
+   * Initializes the observable state handler with given state and configuration.
+   */
   protected constructor({ initialState, options }: ObservableStateHandlerProps<S>) {
+    // Pass the initial state to the base handler.
     super(initialState);
+    // Initialize the internal BehaviorSubject with the initial state.
     this.state$ = new BehaviorSubject<S>(initialState);
+    // Resolve the final distinct options based on provided configuration.
     this.distinctOptions = resolveDistinctOptions(
       options?.distinct,
       options?.useDistinctUntilChanged
     );
+    // Initialize Redux DevTools integration.
     this.initDevTools(options?.devTools);
   }
 
+  /**
+   * Internal implementation of getting the state value via BehaviorSubject.
+   */
   protected getStateValue() {
     return this.state$.getValue();
   }
 
+  /**
+   * Internal implementation of updating the state value via BehaviorSubject.
+   */
   protected setStateValue(nextState: S) {
+    // Notify the subject and all its subscribers of the new state.
     this.state$.next(nextState);
   }
 
+  /**
+   * Returns an observable tracking a specific key within the state object.
+   * Only emits when the value of the specified key actually changes.
+   */
   getObservableItem<K extends keyof S>(key: K): Observable<S[K]> {
     return this.state$.pipe(
+      // Ensure we only emit if the value associated with the key has changed.
       distinctUntilKeyChanged(key),
+      // Transform the state object into the specific key value.
       map((state) => state[key])
     );
   }
 
+  /**
+   * Returns an observable tracking the entire state object.
+   * Can be configured to emit only when the state object effectively changes.
+   */
   getObservable(options: StateObservableOptions = {}): Observable<S> {
+    // Determine whether distinct emissions are enabled.
     const useDistinctUntilChanged = options.useDistinctUntilChanged ?? this.distinctOptions.enabled;
 
+    // If distinct emissions are not enabled, return the subject as-is.
     if (!useDistinctUntilChanged) {
       return this.state$;
     }
 
+    // Apply the distinctUntilChanged operator to filter out redundant updates.
     return this.state$.pipe(
       distinctUntilChanged((previous, next) => {
+        // Use the resolved comparator to compare the previous and next states.
         return this.distinctOptions.comparator(previous, next);
       })
     );
   }
 
+  /**
+   * Subscribes a listener function to state changes via the internal observable.
+   * Overloaded to handle both void and state-receiving listeners.
+   */
   subscribe(listener: () => void): () => void;
   subscribe(listener: (value: S) => void): () => void;
   subscribe(listener: (value: S) => void) {
+    // Subscribe to the state observable and call the listener on each emission.
     const subscription = this.getObservable().subscribe((nextState) => {
       listener(nextState);
     });
+    // Return an unsubscribe function to properly clean up the RxJS subscription.
     return () => subscription.unsubscribe();
   }
 }

package/src/store/signal-state-handler.ts

@@ -1,13 +1,27 @@
+/**
+ * Import signal-based state primitives from @preact/signals-core.
+ */
 import { signal } from '@preact/signals-core';
 
+/**
+ * Import internal configuration and the abstract base state handler.
+ */
 import { resolveDistinctOptions } from '../config/status-quo-config.js';
 import { BaseStateHandler } from './base-state-handler.js';
 
+/**
+ * Import necessary types for DevTools, distinct update options, and Preact Signals.
+ */
 import type { DevToolsOptions, DistinctOptions } from '../config/status-quo-config.js';
 import type { Signal } from '@preact/signals-core';
 
+/**
+ * Props for configuring the SignalStateHandler instance.
+ */
 type SignalStateHandlerProps<S> = {
+  // The initial value for the state.
   initialState: S;
+  // Optional configuration for DevTools and distinct update behaviors.
   options?: {
     devTools?: DevToolsOptions;
     distinct?: DistinctOptions<S>;
@@ -15,32 +29,55 @@ type SignalStateHandlerProps<S> = {
   };
 };
 
+/**
+ * SignalStateHandler: A state handler built on top of Preact Signals.
+ * Provides fine-grained reactivity and efficient state updates.
+ */
 export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
+  // Internal Signal to manage the state with high performance.
   private readonly state: Signal<S>;
+  // Configuration to determine if and how state changes should trigger notifications.
   private readonly distinctOptions: ReturnType<typeof resolveDistinctOptions<S>>;
 
+  /**
+   * Initializes the signal state handler with given state and configuration.
+   */
   protected constructor({ initialState, options }: SignalStateHandlerProps<S>) {
+    // Pass the initial state to the base handler.
     super(initialState);
-
+    // Initialize the internal Signal with the initial state.
     this.state = signal<S>(initialState);
+    // Resolve the final distinct options based on provided configuration.
     this.distinctOptions = resolveDistinctOptions(
       options?.distinct,
       options?.useDistinctUntilChanged
     );
+    // Initialize Redux DevTools integration.
     this.initDevTools(options?.devTools);
   }
 
+  /**
+   * Returns the underlying signal for external use (e.g., in reactive templates).
+   */
   getSignal() {
     return this.state;
   }
 
+  /**
+   * Subscribes a listener function to state changes via the internal signal.
+   * Overloaded to handle both void and state-receiving listeners.
+   */
   subscribe(listener: () => void): () => void;
   subscribe(listener: (value: S) => void): () => void;
   subscribe(listener: (value: S) => void) {
+    // Track whether the listener has been initialized during the first emission.
     let initialized = false;
+    // Keep track of the previous state snapshot for comparison.
     let previousSnapshot = this.state.value;
 
+    // Use the Signal's subscription method.
     return this.state.subscribe((nextState) => {
+      // If this is the initial emission, notify the listener and mark as initialized.
       if (!initialized) {
         initialized = true;
         previousSnapshot = nextState;
@@ -48,6 +85,7 @@ export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
         return;
       }
 
+      // If distinct mode is enabled and the state hasn't effectively changed, stop here.
       if (
         this.distinctOptions.enabled &&
         this.distinctOptions.comparator(previousSnapshot, nextState)
@@ -56,16 +94,24 @@ export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
         return;
       }
 
+      // Update the previous snapshot and notify the listener.
       previousSnapshot = nextState;
       listener(nextState);
     });
   }
 
+  /**
+   * Internal implementation of getting the state value via the Signal's value property.
+   */
   protected getStateValue() {
     return this.state.value;
   }
 
+  /**
+   * Internal implementation of updating the state value via the Signal's value property.
+   */
   protected setStateValue(nextState: S) {
+    // Update the Signal's value, which automatically notifies its subscribers.
     this.state.value = nextState;
   }
 }

package/src/store/state-singleton.ts

@@ -1,39 +1,69 @@
+/**
+ * Import necessary type for state subscription management.
+ */
 import type { StateSubscriptionHandler } from '../types/types.js';
 
+/**
+ * Interface representing a singleton state handler.
+ * Provides a method to get the single instance of a state handler.
+ */
 export interface StateSingleton<V, A> {
+  // Access the singleton instance of the state handler.
   getInstance: () => StateSubscriptionHandler<V, A>;
 }
 
+/**
+ * Options for configuring the behavior of a state singleton.
+ */
 export interface StateSingletonOptions {
+  // Whether to automatically destroy the instance when no more consumers are active.
   destroyOnNoConsumers?: boolean;
 }
 
+/**
+ * Factory function to create a singleton state handler.
+ * Ensures only one instance of the state handler exists throughout the application.
+ */
 export function makeStateSingleton<S, A>(
+  // Function responsible for creating the state handler instance when needed.
   stateHandlerFactory: () => StateSubscriptionHandler<S, A>,
+  // Optional configuration for the singleton.
   { destroyOnNoConsumers = false }: StateSingletonOptions = {}
 ): StateSingleton<S, A> {
+  // Internal variable to store the shared instance of the state handler.
   let instance: StateSubscriptionHandler<S, A> | null = null;
+
+  // The singleton object with an added internal destroy method.
   const singleton: StateSingleton<S, A> & {
     destroyInstance: () => void;
     destroyOnNoConsumers: boolean;
   } = {
+    // Expose whether this singleton should be destroyed when not in use.
     destroyOnNoConsumers,
+    // Method to get or create the singleton instance.
     getInstance() {
+      // If no instance exists, create it using the factory function.
       if (!instance) {
         instance = stateHandlerFactory();
       }
 
+      // Return the current instance.
       return instance;
     },
+    // Method to manually destroy the singleton instance and its resources.
     destroyInstance() {
+      // If no instance exists, there's nothing to destroy.
       if (!instance) {
         return;
       }
 
+      // Call the destroy method on the instance to clean up its resources.
       instance.destroy();
+      // Clear the internal reference to the instance.
       instance = null;
     },
   };
 
+  // Return the created singleton object.
   return singleton;
 }

package/src/types/types.ts

@@ -1,8 +1,24 @@
+/**
+ * Common types and interfaces for state management.
+ */
+
+/**
+ * Interface representing a standard state handler with subscription support.
+ * Used by React hooks and other components to interact with the state store.
+ * V: The type of the state value.
+ * A: The type of the available actions.
+ */
 export interface StateSubscriptionHandler<V, A> {
+  // Method to subscribe a listener to state changes.
   subscribe(listener: () => void): () => void;
+  // Method to subscribe a listener that receives the updated state value.
   subscribe(listener: (value: V) => void): () => void;
+  // Method to retrieve the current state snapshot.
   getSnapshot: () => V;
+  // Method to clean up resources associated with the handler.
   destroy: () => void;
+  // Method to retrieve the initial state value.
   getInitialState: () => V;
+  // Method to retrieve the set of available actions for this handler.
   getActions: () => A;
 }

package/src/utils/selector-cache.ts

@@ -1,43 +1,80 @@
+/**
+ * Utility functions for caching selector results to optimize state updates.
+ */
+
+// Function signature for transforming state into a specific selected value.
 export type Selector<Value, Selected> = (value: Value) => Selected;
+
+// Function signature for comparing two selected values for equality.
 export type EqualityFn<Selected> = (current: Selected, next: Selected) => boolean;
 
+/**
+ * Interface for internal selector cache storage.
+ */
 type SelectorCache<Selected> = {
+  // Whether the cache already contains a computed value.
   hasValue: boolean;
+  // The cached value of the selection result.
   value: Selected | undefined;
 };
 
+/**
+ * Interface for the result of a selection operation.
+ */
 type SelectionResult<Selected> = {
+  // The selected value (either newly computed or from cache).
   value: Selected;
+  // Whether the selected value has effectively changed since the last check.
   hasChanged: boolean;
 };
 
+/**
+ * Creates a new, empty selector cache.
+ * Provides a simple container to track state and values across selections.
+ */
 export function createSelectorCache<Selected>(): SelectorCache<Selected> {
   return {
+    // Initially, no value is stored in the cache.
     hasValue: false,
     value: undefined,
   };
 }
 
+/**
+ * Executes a selector and returns the cached value if the result is considered equal.
+ * This optimization avoids unnecessary re-renders or updates when the derived state is the same.
+ */
 export function selectWithCache<Value, Selected>(
+  // The cache object to store and compare values.
   selectorCache: SelectorCache<Selected>,
+  // The source value from which to select.
   value: Value,
+  // The selector function to transform the source value.
   selector: Selector<Value, Selected>,
+  // Optional equality function to compare selected values (defaults to Object.is).
   isEqual: EqualityFn<Selected> = Object.is
 ): SelectionResult<Selected> {
+  // Execute the selector to derive the current selection value.
   const nextSelection = selector(value);
 
+  // If the cache has a value and the new selection is equal to it, return the cached version.
   if (selectorCache.hasValue && isEqual(selectorCache.value as Selected, nextSelection)) {
     return {
+      // Return the previously cached value to maintain referential stability.
       value: selectorCache.value as Selected,
+      // Signal that no effective change has occurred.
       hasChanged: false,
     };
   }
 
+  // Update the cache with the newly computed selection.
   selectorCache.hasValue = true;
   selectorCache.value = nextSelection;
 
   return {
+    // Return the fresh selection result.
     value: nextSelection,
+    // Signal that the selected value has changed.
     hasChanged: true,
   };
 }