@veams/status-quo 1.5.0 → 1.6.0

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

@@ -1,21 +1,19 @@
-import React from 'react';
-import { act } from 'react';
+import React, { act } from 'react';
 import { createRoot } from 'react-dom/client';
 
-import { makeStateSingleton } from '../../store/state-singleton.js';
-
+import { makeStateSingleton } from '../../../store/state-singleton.js';
 import { useStateActions } from '../state-actions.js';
 import { useStateFactory } from '../state-factory.js';
 import { useStateHandler } from '../state-handler.js';
 import { useStateSingleton } from '../state-singleton.js';
 import { useStateSubscription } from '../state-subscription.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';
 
 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;
 }
 
@@ -153,9 +151,10 @@ class CounterStateHandler implements StateSubscriptionHandler<CounterState, Coun
   };
 }
 
-class CounterMirrorStateHandler
-  implements StateSubscriptionHandler<CounterMirrorState, CounterMirrorActions>
-{
+class CounterMirrorStateHandler implements StateSubscriptionHandler<
+  CounterMirrorState,
+  CounterMirrorActions
+> {
   private readonly initialState: CounterMirrorState;
   private state: CounterMirrorState;
   private readonly listeners = new Set<(value: CounterMirrorState) => void>();
@@ -173,13 +172,15 @@ class CounterMirrorStateHandler
       mirroredCount: initialCounterState.count,
     };
     this.state = this.initialState;
-    this.unsubscribeFromCounter = counterStateHandler.subscribe((nextCounterState: CounterState) => {
-      this.state = {
-        mirroredCount: nextCounterState.count,
-      };
-      const nextMirrorState = this.state;
-      this.listeners.forEach((listener) => listener(nextMirrorState));
-    });
+    this.unsubscribeFromCounter = counterStateHandler.subscribe(
+      (nextCounterState: CounterState) => {
+        this.state = {
+          mirroredCount: nextCounterState.count,
+        };
+        const nextMirrorState = this.state;
+        this.listeners.forEach((listener) => listener(nextMirrorState));
+      }
+    );
   }
 
   subscribe(listener: () => void): () => void;
@@ -235,7 +236,11 @@ type ActionsOnlyConsumerProps = {
   onActionsReady: (actions: TestActions) => void;
 };
 
-const ActionsOnlyConsumer = ({ createStateHandler, onRender, onActionsReady }: ActionsOnlyConsumerProps) => {
+const ActionsOnlyConsumer = ({
+  createStateHandler,
+  onRender,
+  onActionsReady,
+}: ActionsOnlyConsumerProps) => {
   const stateHandler = useStateHandler(createStateHandler, []);
   const actions = useStateActions(stateHandler);
 
@@ -250,13 +255,11 @@ type FactoryShortcutConsumerProps = {
   onRender: (value: string) => void;
 };
 
-const FactoryShortcutConsumer = ({ createStateHandler, onRender }: FactoryShortcutConsumerProps) => {
-  const [userName] = useStateFactory(
-    createStateHandler,
-    (state) => state.user.name,
-    Object.is,
-    []
-  );
+const FactoryShortcutConsumer = ({
+  createStateHandler,
+  onRender,
+}: FactoryShortcutConsumerProps) => {
+  const [userName] = useStateFactory(createStateHandler, (state) => state.user.name, Object.is, []);
   onRender(userName);
 
   return <span>{userName}</span>;
@@ -409,7 +412,7 @@ describe('Selector hooks', () => {
     expect(createStateHandler).toHaveBeenCalledTimes(1);
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     await act(async () => {
@@ -434,7 +437,7 @@ describe('Selector hooks', () => {
       return stateHandler;
     });
     const stateRenderSpy = jest.fn();
-    const actionsReadySpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
 
     act(() => {
       root.render(
@@ -479,7 +482,7 @@ describe('Selector hooks', () => {
       return stateHandler;
     });
     const renderSpy = jest.fn();
-    const actionsReadySpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
 
     act(() => {
       root.render(
@@ -491,7 +494,7 @@ describe('Selector hooks', () => {
       );
     });
 
-    const actions = actionsReadySpy.mock.calls[0][0] as TestActions;
+    const [[actions]] = actionsReadySpy.mock.calls as [[TestActions]];
 
     act(() => {
       actions.increment();
@@ -517,7 +520,9 @@ describe('Selector hooks', () => {
     const renderSpy = jest.fn();
 
     act(() => {
-      root.render(<FactoryShortcutConsumer createStateHandler={createStateHandler} onRender={renderSpy} />);
+      root.render(
+        <FactoryShortcutConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+      );
     });
 
     act(() => {
@@ -577,7 +582,7 @@ describe('Selector hooks', () => {
       return stateHandler;
     });
     const renderSpy = jest.fn();
-    const actionsReadySpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
 
     act(() => {
       root.render(
@@ -594,7 +599,7 @@ describe('Selector hooks', () => {
       counter: 0,
     });
 
-    const actions = actionsReadySpy.mock.calls[0][0] as TestActions;
+    const [[actions]] = actionsReadySpy.mock.calls as [[TestActions]];
 
     act(() => {
       actions.increment();
@@ -611,16 +616,18 @@ describe('Selector hooks', () => {
       user: { name: 'Ada' },
       counter: 0,
     });
-    const singleton = makeStateSingleton(() => stateHandler);
+    const singleton = makeStateSingleton(() => stateHandler, {
+      destroyOnNoConsumers: true,
+    });
     const firstRenderSpy = jest.fn();
     const secondRenderSpy = jest.fn();
 
     act(() => {
       root.render(
-        <>
+        <React.Fragment>
           <SingletonShortcutConsumer singleton={singleton} onRender={firstRenderSpy} />
           <SingletonShortcutConsumer singleton={singleton} onRender={secondRenderSpy} />
-        </>
+        </React.Fragment>
       );
     });
 
@@ -645,7 +652,7 @@ describe('Selector hooks', () => {
     expect(stateHandler.destroy).not.toHaveBeenCalled();
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(stateHandler.destroy).toHaveBeenCalledTimes(1);
@@ -683,7 +690,7 @@ describe('Selector hooks', () => {
     });
     const singleton = makeStateSingleton(() => stateHandler);
     const renderSpy = jest.fn();
-    const actionsReadySpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
 
     act(() => {
       root.render(
@@ -695,7 +702,7 @@ describe('Selector hooks', () => {
       );
     });
 
-    const actions = actionsReadySpy.mock.calls[0][0] as TestActions;
+    const [[actions]] = actionsReadySpy.mock.calls as [[TestActions]];
 
     act(() => {
       actions.increment();
@@ -710,7 +717,7 @@ describe('Selector hooks', () => {
     expect(renderSpy).toHaveBeenCalledTimes(2);
   });
 
-  it('useStateSingleton selector should respect destroyOnNoConsumers false', () => {
+  it('useStateSingleton selector should keep the singleton instance alive by default', () => {
     const firstHandler = new TestStateHandler({
       user: { name: 'Ada' },
       counter: 0,
@@ -723,9 +730,7 @@ describe('Selector hooks', () => {
       .fn(() => firstHandler as StateSubscriptionHandler<TestState, TestActions>)
       .mockReturnValueOnce(firstHandler)
       .mockReturnValueOnce(secondHandler);
-    const singleton = makeStateSingleton<TestState, TestActions>(createStateHandler, {
-      destroyOnNoConsumers: false,
-    });
+    const singleton = makeStateSingleton<TestState, TestActions>(createStateHandler);
     const renderSpy = jest.fn();
 
     act(() => {
@@ -733,7 +738,7 @@ describe('Selector hooks', () => {
     });
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(firstHandler.destroy).not.toHaveBeenCalled();
@@ -764,7 +769,10 @@ describe('Selector hooks', () => {
     act(() => {
       root.render(
         <React.StrictMode>
-          <StrictModeMirrorFactoryConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+          <StrictModeMirrorFactoryConsumer
+            createStateHandler={createStateHandler}
+            onRender={renderSpy}
+          />
         </React.StrictMode>
       );
     });

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/{hooks → react/hooks}/state-subscription-selector.tsx

@@ -1,8 +1,9 @@
-import { useCallback, useMemo, useSyncExternalStore } from 'react';
-import { createSelectorCache, selectWithCache } from '../utils/selector-cache.js';
+import { useCallback, useRef, useSyncExternalStore } from 'react';
 
-import type { StateSubscriptionHandler } from '../types/types.js';
-import type { EqualityFn, Selector } from '../utils/selector-cache.js';
+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>;
@@ -38,7 +39,13 @@ export function useStateSubscriptionSelector<V, A, Sel>(
   isEqual: EqualityFn<Sel> = Object.is,
   destroyOnCleanup = true
 ) {
-  const selectorCache = useMemo(() => createSelectorCache<Sel>(), [stateSubscriptionHandler]);
+  const selectorCacheRef = useRef<ReturnType<typeof createSelectorCache<Sel>> | null>(null);
+
+  if (!selectorCacheRef.current) {
+    selectorCacheRef.current = createSelectorCache<Sel>();
+  }
+
+  const selectorCache = selectorCacheRef.current;
 
   const subscribe = useCallback(
     (listener: Listener) => {
@@ -75,7 +82,9 @@ export function useStateSubscriptionSelector<V, A, Sel>(
 
         activeDeferredDestroyState.refCount = 0;
         activeDeferredDestroyState.timeoutId = setTimeout(() => {
-          const pendingDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
+          const pendingDeferredDestroyState = deferredDestroyMap.get(
+            sharedStateSubscriptionHandler
+          );
 
           if (!pendingDeferredDestroyState || pendingDeferredDestroyState.refCount > 0) {
             return;

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