@veams/status-quo 1.6.0 → 1.8.0

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';

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

@@ -0,0 +1,291 @@
+import { resetStatusQuoForTests, setupStatusQuo } from '../../config/status-quo-config.js';
+import { NativeStateHandler } from '../native-state-handler.js';
+import { makeStateSingleton } from '../state-singleton.js';
+
+import type { DistinctOptions } from '../../config/status-quo-config.js';
+
+type TestState = { test: string; test2: string };
+type TestActions = { testAction: () => void };
+type TestNativeHandlerOptions = {
+  withDevTools?: boolean;
+  distinct?: DistinctOptions<TestState>;
+  useDistinctUntilChanged?: boolean;
+};
+
+class TestNativeStateHandler extends NativeStateHandler<TestState, TestActions> {
+  constructor({ withDevTools, distinct, useDistinctUntilChanged }: TestNativeHandlerOptions = {}) {
+    super({
+      initialState: {
+        test: 'testValue',
+        test2: 'testValue2',
+      },
+      options: {
+        ...(withDevTools && {
+          devTools: {
+            enabled: true,
+            namespace: 'TestNativeStateHandler',
+          },
+        }),
+        ...(distinct && {
+          distinct,
+        }),
+        ...(typeof useDistinctUntilChanged === 'boolean' && {
+          useDistinctUntilChanged,
+        }),
+      },
+    });
+  }
+
+  getActions(): TestActions {
+    return {
+      testAction: () => {
+        this.setState({ test: 'newValue' });
+      },
+    };
+  }
+}
+
+type CounterState = { count: number };
+type CounterActions = { increase: () => void };
+type CounterBucketSelection = { bucket: number };
+type CounterBucketState = { bucket: number };
+
+class CounterNativeStateHandler extends NativeStateHandler<CounterState, CounterActions> {
+  constructor(initialCount = 0) {
+    super({
+      initialState: {
+        count: initialCount,
+      },
+    });
+  }
+
+  getActions(): CounterActions {
+    return {
+      increase: () => {
+        this.setState({ count: this.getState().count + 1 }, 'increase');
+      },
+    };
+  }
+}
+
+class CounterNativeBridgeStateHandler extends NativeStateHandler<
+  CounterState,
+  { noop: () => void }
+> {
+  constructor(
+    counterSingleton: ReturnType<typeof makeStateSingleton<CounterState, CounterActions>>,
+    onCounterSync: (counterState: CounterState) => void
+  ) {
+    super({
+      initialState: {
+        count: 0,
+      },
+    });
+
+    const counterStateHandler = counterSingleton.getInstance();
+
+    this.bindSubscribable<CounterState, CounterState>(
+      counterStateHandler,
+      (nextCounterState) => {
+        onCounterSync(nextCounterState);
+        this.setState({ count: nextCounterState.count }, 'sync-counter');
+      },
+      (counterState) => counterState
+    );
+  }
+
+  getActions(): { noop: () => void } {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
+class CounterNativeBucketBridgeStateHandler extends NativeStateHandler<
+  CounterBucketState,
+  { noop: () => void }
+> {
+  constructor(
+    counterSingleton: ReturnType<typeof makeStateSingleton<CounterState, CounterActions>>,
+    onCounterSync: (selection: CounterBucketSelection) => void
+  ) {
+    super({
+      initialState: {
+        bucket: -1,
+      },
+    });
+
+    const counterStateHandler = counterSingleton.getInstance();
+
+    this.bindSubscribable<CounterState, CounterBucketSelection>(
+      counterStateHandler,
+      (nextSelection) => {
+        onCounterSync(nextSelection);
+        this.setState({ bucket: nextSelection.bucket }, 'sync-counter-bucket');
+      },
+      (counterState) => ({
+        bucket: Math.floor(counterState.count / 2),
+      }),
+      (current, next) => current.bucket === next.bucket
+    );
+  }
+
+  getActions(): { noop: () => void } {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
+describe('Native State Handler', () => {
+  let stateHandler: TestNativeStateHandler;
+
+  beforeEach(() => {
+    resetStatusQuoForTests();
+    stateHandler = new TestNativeStateHandler();
+  });
+
+  afterEach(() => {
+    resetStatusQuoForTests();
+  });
+
+  it('should provide initial state', () => {
+    expect(stateHandler.getInitialState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should provide current state', () => {
+    expect(stateHandler.getState()).toStrictEqual({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+  });
+
+  it('should support state changing via setter and merge state object on first level', () => {
+    const expected = {
+      test: 'change',
+      test2: 'testValue2',
+    };
+
+    stateHandler.setState(expected);
+
+    expect(stateHandler.getState()).toStrictEqual(expected);
+  });
+
+  it('should support additional subscriptions handling', () => {
+    const spy = jest.fn();
+    const subscription = { unsubscribe: spy };
+
+    stateHandler.subscriptions = [subscription];
+
+    stateHandler.destroy();
+
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should call subscriber when state has changed and also on initial subscribe', () => {
+    const spy = jest.fn();
+    const unsubscribe = stateHandler.subscribe(spy);
+
+    stateHandler.setState({
+      test: 'test',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+    stateHandler.setState({
+      test: 'test2',
+    });
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(3); // initial + change + change
+  });
+
+  it('should respect global distinct setup when disabled', () => {
+    setupStatusQuo({
+      distinct: {
+        enabled: false,
+      },
+    });
+
+    const handler = new TestNativeStateHandler();
+    const spy = jest.fn();
+    const unsubscribe = handler.subscribe(spy);
+
+    handler.setState({ test: 'same' });
+    handler.setState({ test: 'same' });
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(3); // initial + change + change
+  });
+
+  it('should respect global custom distinct comparator from setupStatusQuo', () => {
+    setupStatusQuo({
+      distinct: {
+        comparator: (previous: TestState, next: TestState) => {
+          return previous.test === next.test;
+        },
+      },
+    });
+
+    const handler = new TestNativeStateHandler();
+    const spy = jest.fn();
+    const unsubscribe = handler.subscribe(spy);
+
+    handler.setState({ test2: 'newValue2' }); // test remains same -> skipped
+    handler.setState({ test: 'newValue' }); // test changed -> notified
+
+    unsubscribe();
+
+    expect(spy).toHaveBeenCalledTimes(2); // initial + one change
+  });
+
+  it('should notify another state handler for each singleton counter update', () => {
+    const counterSingleton = makeStateSingleton(() => new CounterNativeStateHandler(0), {
+      destroyOnNoConsumers: false,
+    });
+    const syncSpy = jest.fn();
+    const bridgeStateHandler = new CounterNativeBridgeStateHandler(counterSingleton, syncSpy);
+    const counterStateHandler = counterSingleton.getInstance();
+
+    counterStateHandler.getActions().increase();
+    counterStateHandler.getActions().increase();
+
+    expect(syncSpy).toHaveBeenCalledTimes(3);
+    expect(syncSpy).toHaveBeenNthCalledWith(1, { count: 0 });
+    expect(syncSpy).toHaveBeenNthCalledWith(2, { count: 1 });
+    expect(syncSpy).toHaveBeenNthCalledWith(3, { count: 2 });
+    expect(bridgeStateHandler.getState()).toStrictEqual({ count: 2 });
+
+    bridgeStateHandler.destroy();
+  });
+
+  it('should support selector + equality filtering for bindSubscribable', () => {
+    const counterSingleton = makeStateSingleton(() => new CounterNativeStateHandler(0), {
+      destroyOnNoConsumers: false,
+    });
+    const syncSpy = jest.fn();
+    const bridgeStateHandler = new CounterNativeBucketBridgeStateHandler(counterSingleton, syncSpy);
+    const counterStateHandler = counterSingleton.getInstance();
+
+    counterStateHandler.getActions().increase(); // count 1 -> bucket 0 (no change)
+    counterStateHandler.getActions().increase(); // count 2 -> bucket 1
+    counterStateHandler.getActions().increase(); // count 3 -> bucket 1 (no change)
+    counterStateHandler.getActions().increase(); // count 4 -> bucket 2
+
+    expect(syncSpy).toHaveBeenCalledTimes(3);
+    expect(syncSpy).toHaveBeenNthCalledWith(1, { bucket: 0 });
+    expect(syncSpy).toHaveBeenNthCalledWith(2, { bucket: 1 });
+    expect(syncSpy).toHaveBeenNthCalledWith(3, { bucket: 2 });
+    expect(bridgeStateHandler.getState()).toStrictEqual({ bucket: 2 });
+
+    bridgeStateHandler.destroy();
+  });
+});

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

@@ -5,6 +5,14 @@ import { ObservableStateHandler } from '../observable-state-handler.js';
 
 import type { DevToolsOptions, DistinctOptions } from '../../config/status-quo-config.js';
 
+declare global {
+  interface Window {
+    __REDUX_DEVTOOLS_EXTENSION__?: {
+      connect: (options: any) => any;
+    };
+  }
+}
+
 type TestState = { test: string; test2: string };
 type TestActions = { testAction: () => void };
 type TestObservableHandlerOptions = {