AI docs

Author: arnautov-anton

src/store.ts

@@ -58,7 +58,7 @@ export class StateStore<T extends Record<string, unknown>> {
   public getLatestValue(): T {
     return this.value;
   }
-  
+
   public subscribe(handler: Handler<T>): Unsubscribe {
     handler(this.value, undefined);
     this.handlers.add(handler);
@@ -107,6 +107,19 @@ export class StateStore<T extends Record<string, unknown>> {
   }
 }
 
+/**
+ * Represents a merged state store that combines two separate state stores into one.
+ *
+ * The MergedStateStore allows combining two stores with non-overlapping keys.
+ * It extends StateStore with the combined type of both source stores.
+ * Changes to either the original or merged store will propagate to the combined store.
+ *
+ * Note: Direct mutations (next, partialNext, registerModifier) are disabled on the merged store.
+ * You should instead call these methods on the original or merged stores.
+ *
+ * @template O The type of the original state store
+ * @template M The type of the merged state store
+ */
 class MergedStateStore<
   O extends Record<string, unknown>,
   M extends Record<string, unknown>,
@@ -132,6 +145,21 @@ class MergedStateStore<
     this.merged = merged;
   }
 
+  /**
+   * Subscribes to changes in the merged state store.
+   *
+   * This method extends the base subscribe functionality to handle the merged nature of this store:
+   * 1. The first subscriber triggers registration of helper subscribers that listen to both source stores
+   * 2. Changes from either source store are propagated to this merged store
+   * 3. Source store values are cached to prevent unnecessary updates
+   *
+   * When the first subscriber is added, the method sets up listeners on both original and merged stores.
+   * These listeners update the combined store value whenever either source store changes.
+   * All subscriptions (helpers and the actual handler) are tracked so they can be properly cleaned up.
+   *
+   * @param handler - The callback function that will be executed when the state changes
+   * @returns An unsubscribe function that, when called, removes the subscription and any helper subscriptions
+   */
   public subscribe(handler: Handler<O & M>) {
     const unsubscribeFunctions: Unsubscribe[] = [];
 
@@ -169,6 +197,24 @@ class MergedStateStore<
     };
   }
 
+  /**
+   * Retrieves the latest combined state from both original and merged stores.
+   *
+   * This method extends the base getLatestValue functionality to ensure the merged store
+   * remains in sync with its source stores even when there are no active subscribers.
+   *
+   * When there are no handlers registered, the method:
+   * 1. Fetches the latest values from both source stores
+   * 2. Compares them with the cached values to detect changes
+   * 3. If changes are detected, updates the internal value and caches
+   *    the new source values to maintain consistency
+   *
+   * This approach ensures that calling getLatestValue() always returns the most
+   * up-to-date combined state, even if the merged store hasn't been actively
+   * receiving updates through subscriptions.
+   *
+   * @returns The latest combined state from both original and merged stores
+   */
   public getLatestValue() {
     // if there are no handlers registered to MergedStore then the local value might be out-of-sync
     // pull latest and compare against cached - if they differ, cache latest and produce new combined