@veams/status-quo 1.5.1 → 1.7.0

package/src/{hooks → react/hooks}/__tests__/state-singleton.spec.tsx

@@ -1,16 +1,14 @@
-import React from 'react';
-import { act } from 'react';
+import React, { act } from 'react';
 import { createRoot } from 'react-dom/client';
 
+import { makeStateSingleton } from '../../../store';
 import { useStateSingleton } from '../state-singleton.js';
 
-import { makeStateSingleton } from '../../store';
-
-import type { StateSubscriptionHandler } from '../../types/types.js';
+import type { StateSubscriptionHandler } from '../../../types/types.js';
 
 declare global {
   // React 19 requires this flag in test environments that use manual act() calls.
-  // eslint-disable-next-line no-var
+   
   var IS_REACT_ACT_ENVIRONMENT: boolean;
 }
 
@@ -39,7 +37,11 @@ const createStateHandler = (value: number): TestHandler => {
   };
 };
 
-const SingletonConsumer = ({ singleton }: { singleton: ReturnType<typeof makeStateSingleton<TestState, TestActions>> }) => {
+const SingletonConsumer = ({
+  singleton,
+}: {
+  singleton: ReturnType<typeof makeStateSingleton<TestState, TestActions>>;
+}) => {
   useStateSingleton(singleton);
 
   return null;
@@ -77,10 +79,10 @@ describe('useStateSingleton', () => {
 
     act(() => {
       root.render(
-        <>
+        <React.Fragment>
           <SingletonConsumer singleton={singleton} />
           <SingletonConsumer singleton={singleton} />
-        </>
+        </React.Fragment>
       );
     });
 
@@ -91,27 +93,28 @@ describe('useStateSingleton', () => {
     expect(firstHandler.destroy).not.toHaveBeenCalled();
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
-    expect(firstHandler.destroy).toHaveBeenCalledTimes(1);
+    expect(firstHandler.destroy).not.toHaveBeenCalled();
   });
 
-  it('should create a new singleton instance after all consumers unmount', () => {
+  it('should create a new singleton instance after all consumers unmount when destroyOnNoConsumers is true', () => {
     const firstHandler = createStateHandler(1);
     const secondHandler = createStateHandler(2);
     const factory = jest.fn(() => firstHandler as StateSubscriptionHandler<TestState, TestActions>);
 
     factory.mockReturnValueOnce(firstHandler).mockReturnValueOnce(secondHandler);
-
-    const singleton = makeStateSingleton<TestState, TestActions>(factory);
+    const singleton = makeStateSingleton<TestState, TestActions>(factory, {
+      destroyOnNoConsumers: true,
+    });
 
     act(() => {
       root.render(<SingletonConsumer singleton={singleton} />);
     });
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(firstHandler.destroy).toHaveBeenCalledTimes(1);
@@ -124,19 +127,17 @@ describe('useStateSingleton', () => {
     expect(singleton.getInstance().getSnapshot()).toStrictEqual({ value: 2 });
   });
 
-  it('should keep singleton instance alive when destroyOnNoConsumers is false', () => {
+  it('should keep singleton instance alive by default', () => {
     const firstHandler = createStateHandler(1);
     const factory = jest.fn(() => firstHandler as StateSubscriptionHandler<TestState, TestActions>);
-    const singleton = makeStateSingleton<TestState, TestActions>(factory, {
-      destroyOnNoConsumers: false,
-    });
+    const singleton = makeStateSingleton<TestState, TestActions>(factory);
 
     act(() => {
       root.render(<SingletonConsumer singleton={singleton} />);
     });
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(firstHandler.destroy).not.toHaveBeenCalled();

package/src/react/hooks/index.ts

@@ -0,0 +1,11 @@
+export { useStateActions } from './state-actions.js';
+export { useStateFactory } from './state-factory.js';
+export { useStateHandler } from './state-handler.js';
+export {
+  StateProvider,
+  useProvidedStateActions,
+  useProvidedStateHandler,
+  useProvidedStateSubscription,
+} from './state-provider.js';
+export { useStateSingleton } from './state-singleton.js';
+export { useStateSubscription } from './state-subscription.js';

package/src/{hooks → react/hooks}/state-actions.tsx

@@ -1,6 +1,6 @@
 import { useMemo } from 'react';
 
-import type { StateSubscriptionHandler } from '../types/types.js';
+import type { StateSubscriptionHandler } from '../../types/types.js';
 
 export function useStateActions<V, A>(stateSubscriptionHandler: StateSubscriptionHandler<V, A>) {
   return useMemo(() => stateSubscriptionHandler.getActions(), [stateSubscriptionHandler]);

package/src/{hooks → react/hooks}/state-factory.tsx

@@ -1,7 +1,7 @@
 import { useStateHandler } from './state-handler.js';
 import { useStateSubscription } from './state-subscription.js';
 
-import type { StateSubscriptionHandler } from '../types/types.js';
+import type { StateSubscriptionHandler } from '../../types/types.js';
 
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
@@ -32,7 +32,7 @@ export function useStateFactory<V, A, P extends unknown[], Sel = V>(
   const hasSelector = typeof selectorOrParams === 'function';
   const selector = (hasSelector ? selectorOrParams : identitySelector) as StateSelector<V, Sel>;
   const hasCustomEquality = hasSelector && typeof isEqualOrParams === 'function';
-  const isEqual = (hasCustomEquality ? isEqualOrParams : Object.is) as EqualityFn<Sel>;
+  const isEqual = (hasCustomEquality ? isEqualOrParams : Object.is);
   const stateFactoryParams = (
     hasSelector ? (hasCustomEquality ? params : isEqualOrParams) : selectorOrParams
   ) as P;

package/src/{hooks → react/hooks}/state-handler.tsx

@@ -1,6 +1,6 @@
 import { useRef } from 'react';
 
-import type { StateSubscriptionHandler } from '../types/types.js';
+import type { StateSubscriptionHandler } from '../../types/types.js';
 
 export function useStateHandler<V, A, P extends unknown[]>(
   stateFactoryFunction: (...args: P) => StateSubscriptionHandler<V, A>,

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

@@ -0,0 +1,56 @@
+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<{
+  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>;
+}
+
+export function StateProvider<V, A>({ children, instance }: StateProviderProps<V, A>) {
+  return (
+    <StateProviderContext.Provider value={instance as SharedStateHandler}>
+      {children}
+    </StateProviderContext.Provider>
+  );
+}
+
+export function useProvidedStateActions<V, A>() {
+  const stateHandler = useProvidedStateHandler<V, A>();
+
+  return useStateActions(stateHandler);
+}
+
+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/{hooks → react/hooks}/state-singleton.tsx

@@ -1,6 +1,6 @@
 import { useStateSubscription } from './state-subscription.js';
 
-import type { StateSingleton } from '../store/state-singleton.js';
+import type { StateSingleton } from '../../store/state-singleton.js';
 
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;

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

@@ -0,0 +1,190 @@
+import { useCallback, useRef, useSyncExternalStore } from 'react';
+
+import { createSelectorCache, selectWithCache } from '../../utils/selector-cache.js';
+
+import type { StateSubscriptionHandler } from '../../types/types.js';
+import type { EqualityFn, Selector } from '../../utils/selector-cache.js';
+
+type Listener = () => void;
+type SharedStateSubscriptionHandler = StateSubscriptionHandler<unknown, unknown>;
+type DeferredDestroy = {
+  refCount: number;
+  timeoutId: ReturnType<typeof setTimeout> | null;
+};
+type SnapshotCacheEntry<Source, Selected> = {
+  selectedSnapshot: Selected;
+  sourceSnapshot: Source;
+  version: number;
+};
+type ServerSnapshotCacheEntry<Source, Selected> = {
+  selectedSnapshot: Selected;
+  sourceSnapshot: Source;
+};
+
+const deferredDestroyMap = new WeakMap<SharedStateSubscriptionHandler, DeferredDestroy>();
+
+function getDeferredDestroyState(
+  stateSubscriptionHandler: SharedStateSubscriptionHandler
+): DeferredDestroy {
+  const existingState = deferredDestroyMap.get(stateSubscriptionHandler);
+
+  if (existingState) {
+    return existingState;
+  }
+
+  const nextState: DeferredDestroy = {
+    refCount: 0,
+    timeoutId: null,
+  };
+
+  deferredDestroyMap.set(stateSubscriptionHandler, nextState);
+
+  return nextState;
+}
+
+export function useStateSubscriptionSelector<V, A, Sel>(
+  stateSubscriptionHandler: StateSubscriptionHandler<V, A>,
+  selector: Selector<V, Sel>,
+  isEqual: EqualityFn<Sel> = Object.is,
+  destroyOnCleanup = true
+) {
+  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.
+  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);
+
+  if (!selectorCacheRef.current) {
+    selectorCacheRef.current = createSelectorCache<Sel>();
+  }
+
+  const selectorCache = selectorCacheRef.current;
+
+  const subscribe = useCallback(
+    (listener: Listener) => {
+      const sharedStateSubscriptionHandler =
+        stateSubscriptionHandler as unknown as SharedStateSubscriptionHandler;
+      const deferredDestroyState = getDeferredDestroyState(sharedStateSubscriptionHandler);
+      deferredDestroyState.refCount += 1;
+
+      if (deferredDestroyState.timeoutId) {
+        clearTimeout(deferredDestroyState.timeoutId);
+        deferredDestroyState.timeoutId = null;
+      }
+
+      const unsubscribe = stateSubscriptionHandler.subscribe(() => {
+        // Invalidate the selected snapshot cache before notifying React.
+        // Any next getSnapshot call should recompute from the new store state.
+        snapshotVersionRef.current += 1;
+        snapshotCacheRef.current = null;
+        listener();
+      });
+
+      return () => {
+        unsubscribe();
+
+        if (!destroyOnCleanup) {
+          return;
+        }
+
+        const activeDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
+
+        if (!activeDeferredDestroyState) {
+          return;
+        }
+
+        activeDeferredDestroyState.refCount -= 1;
+
+        if (activeDeferredDestroyState.refCount > 0) {
+          return;
+        }
+
+        activeDeferredDestroyState.refCount = 0;
+        activeDeferredDestroyState.timeoutId = setTimeout(() => {
+          const pendingDeferredDestroyState = deferredDestroyMap.get(
+            sharedStateSubscriptionHandler
+          );
+
+          if (!pendingDeferredDestroyState || pendingDeferredDestroyState.refCount > 0) {
+            return;
+          }
+
+          pendingDeferredDestroyState.timeoutId = null;
+          stateSubscriptionHandler.destroy();
+          deferredDestroyMap.delete(sharedStateSubscriptionHandler);
+        }, 0);
+      };
+    },
+    [destroyOnCleanup, stateSubscriptionHandler]
+  );
+
+  const selectSnapshot = useCallback(
+    (snapshot: V) => {
+      return selectWithCache(selectorCache, snapshot, selector, isEqual).value;
+    },
+    [isEqual, selector, selectorCache]
+  );
+
+  const selectorCacheControlRef = useRef(selectSnapshot);
+
+  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;
+  }
+
+  const getSnapshot = useCallback(
+    () => {
+      const sourceSnapshot = stateSubscriptionHandler.getSnapshot();
+      const version = snapshotVersionRef.current;
+      const cachedSnapshot = snapshotCacheRef.current;
+
+      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;
+      }
+
+      const selectedSnapshot = selectSnapshot(sourceSnapshot);
+      snapshotCacheRef.current = {
+        selectedSnapshot,
+        sourceSnapshot,
+        version,
+      };
+
+      return selectedSnapshot;
+    },
+    [selectSnapshot, stateSubscriptionHandler]
+  );
+
+  const getServerSnapshot = useCallback(
+    () => {
+      const sourceSnapshot = stateSubscriptionHandler.getInitialState();
+      const cachedSnapshot = serverSnapshotCacheRef.current;
+
+      if (cachedSnapshot && Object.is(cachedSnapshot.sourceSnapshot, sourceSnapshot)) {
+        // Keep server snapshot reads stable for hydration by reusing cached selection.
+        return cachedSnapshot.selectedSnapshot;
+      }
+
+      const selectedSnapshot = selectSnapshot(sourceSnapshot);
+      serverSnapshotCacheRef.current = {
+        selectedSnapshot,
+        sourceSnapshot,
+      };
+
+      return selectedSnapshot;
+    },
+    [selectSnapshot, stateSubscriptionHandler]
+  );
+
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/{hooks → react/hooks}/state-subscription.tsx

@@ -3,8 +3,8 @@ import { useEffect, useMemo } from 'react';
 import { useStateActions } from './state-actions.js';
 import { useStateSubscriptionSelector } from './state-subscription-selector.js';
 
-import type { StateSingleton } from '../store/state-singleton.js';
-import type { StateSubscriptionHandler } from '../types/types.js';
+import type { StateSingleton } from '../../store/state-singleton.js';
+import type { StateSubscriptionHandler } from '../../types/types.js';
 
 type StateSelector<State, SelectedState> = (state: State) => SelectedState;
 type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
@@ -27,17 +27,13 @@ function isStateSingleton<V, A>(
   return 'getInstance' in source;
 }
 
-export function useStateSubscription<V, A>(
-  source: StateSubscriptionHandler<V, A>
-): [V, A];
+export function useStateSubscription<V, A>(source: StateSubscriptionHandler<V, A>): [V, A];
 export function useStateSubscription<V, A, Sel>(
   source: StateSubscriptionHandler<V, A>,
   selector: StateSelector<V, Sel>,
   isEqual?: EqualityFn<Sel>
 ): [Sel, A];
-export function useStateSubscription<V, A>(
-  source: StateSingleton<V, A>
-): [V, A];
+export function useStateSubscription<V, A>(source: StateSingleton<V, A>): [V, A];
 export function useStateSubscription<V, A, Sel>(
   source: StateSingleton<V, A>,
   selector: StateSelector<V, Sel>,
@@ -83,7 +79,7 @@ export function useStateSubscription<V, A, Sel = V>(
 
       if (activeReference.count <= 0) {
         singletonReferences.delete(singleton);
-        if (singleton.destroyOnNoConsumers === false) {
+        if (singleton.destroyOnNoConsumers !== true) {
           return;
         }
 

package/src/react/index.ts

@@ -0,0 +1 @@
+export * from './hooks/index.js';

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

@@ -2,30 +2,30 @@ import { lastValueFrom, Subject, take } from 'rxjs';
 
 import { resetStatusQuoForTests, setupStatusQuo } from '../../config/status-quo-config.js';
 import { ObservableStateHandler } from '../observable-state-handler.js';
-import type { DistinctOptions } from '../../config/status-quo-config.js';
+
+import type { DevToolsOptions, DistinctOptions } from '../../config/status-quo-config.js';
 
 type TestState = { test: string; test2: string };
 type TestActions = { testAction: () => void };
 type TestObservableHandlerOptions = {
-  withDevTools?: boolean;
+  devTools?: DevToolsOptions;
   distinct?: DistinctOptions<TestState>;
   useDistinctUntilChanged?: boolean;
 };
 
 class TestObservableStateHandler extends ObservableStateHandler<TestState, TestActions> {
-  constructor({ withDevTools, distinct, useDistinctUntilChanged }: TestObservableHandlerOptions = {}) {
+  constructor({
+    devTools,
+    distinct,
+    useDistinctUntilChanged,
+  }: TestObservableHandlerOptions = {}) {
     super({
       initialState: {
         test: 'testValue',
         test2: 'testValue2',
       },
       options: {
-        ...(withDevTools && {
-          devTools: {
-            enabled: true,
-            namespace: 'TestObservableStateHandler',
-          },
-        }),
+        ...(devTools && { devTools }),
         ...(distinct && {
           distinct,
         }),
@@ -48,12 +48,26 @@ class TestObservableStateHandler extends ObservableStateHandler<TestState, TestA
 describe('Observable State Handler', () => {
   let stateHandler: TestObservableStateHandler;
 
+  function mockDevToolsExtension() {
+    const devTools = {
+      init: jest.fn(),
+      send: jest.fn(),
+      subscribe: jest.fn(),
+    };
+    const connect = jest.fn(() => devTools);
+
+    window.__REDUX_DEVTOOLS_EXTENSION__ = { connect };
+
+    return { connect, devTools };
+  }
+
   beforeEach(() => {
     resetStatusQuoForTests();
     stateHandler = new TestObservableStateHandler();
   });
 
   afterEach(() => {
+    delete window.__REDUX_DEVTOOLS_EXTENSION__;
     resetStatusQuoForTests();
   });
 
@@ -79,7 +93,7 @@ describe('Observable State Handler', () => {
 
     stateHandler.setState(expected);
 
-    const state = await lastValueFrom(stateHandler.getStateAsObservable().pipe(take(1)));
+    const state = await lastValueFrom(stateHandler.getObservable().pipe(take(1)));
 
     expect(state).toStrictEqual(expected);
     expect(stateHandler.getState()).toStrictEqual(expected);
@@ -102,13 +116,13 @@ describe('Observable State Handler', () => {
     expect(spy).toHaveBeenCalledTimes(1);
   });
 
-  it('should expose state item observable via getObservable', async () => {
-    const observableValue = await lastValueFrom(stateHandler.getObservable('test').pipe(take(1)));
+  it('should expose state item observable via getObservableItem', async () => {
+    const observableValue = await lastValueFrom(stateHandler.getObservableItem('test').pipe(take(1)));
 
     expect(observableValue).toBe('testValue');
   });
 
-  it('should only call subscriber when object state has changed', async () => {
+  it('should only call subscriber when object state has changed', () => {
     const spy = jest.fn();
 
     const unsubscribe = stateHandler.subscribe(spy);
@@ -192,4 +206,69 @@ describe('Observable State Handler', () => {
 
     expect(spy).toHaveBeenCalledTimes(2);
   });
+
+  it('should enable devtools from global setup and fall back to the class name as namespace', () => {
+    const { connect, devTools } = mockDevToolsExtension();
+
+    setupStatusQuo({
+      devTools: {
+        enabled: true,
+      },
+    });
+
+    new TestObservableStateHandler();
+
+    expect(connect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instanceId: 'testobservablestatehandler',
+        name: 'TestObservableStateHandler',
+      })
+    );
+    expect(devTools.init).toHaveBeenCalledWith({
+      test: 'testValue',
+      test2: 'testValue2',
+    });
+    expect(devTools.subscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it('should prefer per-handler devtools options over global setup', () => {
+    const { connect } = mockDevToolsExtension();
+
+    setupStatusQuo({
+      devTools: {
+        enabled: true,
+      },
+    });
+
+    new TestObservableStateHandler({
+      devTools: {
+        namespace: 'LocalHandler',
+      },
+    });
+
+    expect(connect).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instanceId: 'localhandler',
+        name: 'LocalHandler',
+      })
+    );
+  });
+
+  it('should allow per-handler devtools settings to disable a global devtools setup', () => {
+    const { connect } = mockDevToolsExtension();
+
+    setupStatusQuo({
+      devTools: {
+        enabled: true,
+      },
+    });
+
+    new TestObservableStateHandler({
+      devTools: {
+        enabled: false,
+      },
+    });
+
+    expect(connect).not.toHaveBeenCalled();
+  });
 });

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

@@ -1,6 +1,7 @@
 import { resetStatusQuoForTests, setupStatusQuo } from '../../config/status-quo-config.js';
 import { SignalStateHandler } from '../signal-state-handler.js';
 import { makeStateSingleton } from '../state-singleton.js';
+
 import type { DistinctOptions } from '../../config/status-quo-config.js';
 
 type TestState = { test: string; test2: string };
@@ -67,7 +68,10 @@ class CounterSignalStateHandler extends SignalStateHandler<CounterState, Counter
   }
 }
 
-class CounterSignalBridgeStateHandler extends SignalStateHandler<CounterState, { noop: () => void }> {
+class CounterSignalBridgeStateHandler extends SignalStateHandler<
+  CounterState,
+  { noop: () => void }
+> {
   constructor(
     counterSingleton: ReturnType<typeof makeStateSingleton<CounterState, CounterActions>>,
     onCounterSync: (counterState: CounterState) => void