@veams/status-quo 1.5.1 → 1.7.0

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

@@ -0,0 +1,286 @@
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import {
+  StateProvider,
+  useProvidedStateActions,
+  useProvidedStateHandler,
+  useProvidedStateSubscription,
+} from '../state-provider.js';
+
+import type { StateSubscriptionHandler } from '../../../types/types.js';
+
+declare global {
+  // React 19 requires this flag in test environments that use manual act() calls.
+
+  var IS_REACT_ACT_ENVIRONMENT: boolean;
+}
+
+type TestState = {
+  count: number;
+  label: string;
+};
+
+type TestActions = {
+  increment: () => void;
+  rename: (label: string) => void;
+};
+
+class TestStateHandler implements StateSubscriptionHandler<TestState, TestActions> {
+  private readonly initialState: TestState;
+  private state: TestState;
+  private readonly listeners = new Set<(value: TestState) => void>();
+
+  destroy = jest.fn();
+
+  constructor(initialState: TestState) {
+    this.initialState = initialState;
+    this.state = initialState;
+  }
+
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: TestState) => void): () => void;
+  subscribe(listener: ((value: TestState) => void) | (() => void)) {
+    const typedListener = listener as (value: TestState) => void;
+    this.listeners.add(typedListener);
+
+    return () => {
+      this.listeners.delete(typedListener);
+    };
+  }
+
+  getSnapshot = () => {
+    return this.state;
+  };
+
+  getInitialState = () => {
+    return this.initialState;
+  };
+
+  getActions = () => {
+    return {
+      increment: () => {
+        this.state = {
+          ...this.state,
+          count: this.state.count + 1,
+        };
+
+        this.emitStateChange();
+      },
+      rename: (label: string) => {
+        this.state = {
+          ...this.state,
+          label,
+        };
+
+        this.emitStateChange();
+      },
+    };
+  };
+
+  private emitStateChange() {
+    const nextState = this.state;
+    this.listeners.forEach((listener) => listener(nextState));
+  }
+}
+
+function CountConsumer({ onRender }: { onRender: (count: number) => void }) {
+  const [count] = useProvidedStateSubscription<TestState, TestActions, number>(
+    (state) => state.count
+  );
+
+  onRender(count);
+
+  return <span>{count}</span>;
+}
+
+function FullStateConsumer({
+  onActionsReady,
+  onRender,
+}: {
+  onActionsReady: (actions: TestActions) => void;
+  onRender: (state: TestState) => void;
+}) {
+  const [state, actions] = useProvidedStateSubscription<TestState, TestActions>();
+
+  onRender(state);
+  onActionsReady(actions);
+
+  return <span>{state.label}</span>;
+}
+
+function ActionsOnlyConsumer({
+  onActionsReady,
+  onRender,
+}: {
+  onActionsReady: (actions: TestActions) => void;
+  onRender: () => void;
+}) {
+  const actions = useProvidedStateActions<TestState, TestActions>();
+
+  onRender();
+  onActionsReady(actions);
+
+  return <span>actions-only</span>;
+}
+
+function HandlerConsumer({
+  onHandlerReady,
+}: {
+  onHandlerReady: (handler: StateSubscriptionHandler<TestState, TestActions>) => void;
+}) {
+  const handler = useProvidedStateHandler<TestState, TestActions>();
+
+  onHandlerReady(handler);
+
+  return <span>handler</span>;
+}
+
+function MissingProviderConsumer() {
+  useProvidedStateActions<TestState, TestActions>();
+
+  return null;
+}
+
+describe('StateProvider', () => {
+  let container: HTMLDivElement;
+  let root: ReturnType<typeof createRoot>;
+
+  beforeAll(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+  });
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(() => {
+    act(() => {
+      root.unmount();
+    });
+
+    container.remove();
+  });
+
+  afterAll(() => {
+    globalThis.IS_REACT_ACT_ENVIRONMENT = false;
+  });
+
+  it('should share one handler instance across the provider subtree', () => {
+    const stateHandler = new TestStateHandler({
+      count: 0,
+      label: 'Counter',
+    });
+    const countRenderSpy = jest.fn<void, [number]>();
+    const actionsRenderSpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
+    const handlerReadySpy = jest.fn<void, [StateSubscriptionHandler<TestState, TestActions>]>();
+
+    act(() => {
+      root.render(
+        <StateProvider instance={stateHandler}>
+          <CountConsumer onRender={countRenderSpy} />
+          <ActionsOnlyConsumer onActionsReady={actionsReadySpy} onRender={actionsRenderSpy} />
+          <HandlerConsumer onHandlerReady={handlerReadySpy} />
+        </StateProvider>
+      );
+    });
+
+    expect(countRenderSpy).toHaveBeenCalledTimes(1);
+    expect(countRenderSpy).toHaveBeenLastCalledWith(0);
+    expect(actionsRenderSpy).toHaveBeenCalledTimes(1);
+    expect(handlerReadySpy).toHaveBeenCalledWith(stateHandler);
+
+    const [[actions]] = actionsReadySpy.mock.calls as [[TestActions]];
+
+    act(() => {
+      actions.rename('Renamed');
+    });
+
+    expect(countRenderSpy).toHaveBeenCalledTimes(1);
+    expect(actionsRenderSpy).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      actions.increment();
+    });
+
+    expect(countRenderSpy).toHaveBeenCalledTimes(2);
+    expect(countRenderSpy).toHaveBeenLastCalledWith(1);
+    expect(actionsRenderSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return the full snapshot when no selector is provided', () => {
+    const stateHandler = new TestStateHandler({
+      count: 2,
+      label: 'Counter',
+    });
+    const renderSpy = jest.fn<void, [TestState]>();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
+
+    act(() => {
+      root.render(
+        <StateProvider instance={stateHandler}>
+          <FullStateConsumer onActionsReady={actionsReadySpy} onRender={renderSpy} />
+        </StateProvider>
+      );
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+    expect(renderSpy).toHaveBeenLastCalledWith({ count: 2, label: 'Counter' });
+
+    const [[actions]] = actionsReadySpy.mock.calls as [[TestActions]];
+
+    act(() => {
+      actions.increment();
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(2);
+    expect(renderSpy).toHaveBeenLastCalledWith({ count: 3, label: 'Counter' });
+  });
+
+  it('should follow a new instance when the provider instance changes', () => {
+    const firstHandler = new TestStateHandler({
+      count: 1,
+      label: 'First',
+    });
+    const secondHandler = new TestStateHandler({
+      count: 8,
+      label: 'Second',
+    });
+    const renderSpy = jest.fn<void, [number]>();
+
+    act(() => {
+      root.render(
+        <StateProvider instance={firstHandler}>
+          <CountConsumer onRender={renderSpy} />
+        </StateProvider>
+      );
+    });
+
+    act(() => {
+      root.render(
+        <StateProvider instance={secondHandler}>
+          <CountConsumer onRender={renderSpy} />
+        </StateProvider>
+      );
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(2);
+    expect(renderSpy).toHaveBeenNthCalledWith(1, 1);
+    expect(renderSpy).toHaveBeenNthCalledWith(2, 8);
+  });
+
+  it('should throw when provider hooks are used outside StateProvider', () => {
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    expect(() => {
+      act(() => {
+        root.render(<MissingProviderConsumer />);
+      });
+    }).toThrow('No StateProvider instance found in the current React tree.');
+
+    consoleErrorSpy.mockRestore();
+  });
+});

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>;
@@ -328,6 +331,23 @@ const FullSubscriptionConsumer = ({
   return <span>{state.user.name}</span>;
 };
 
+type ObjectSelectorConsumerProps = {
+  createStateHandler: () => StateSubscriptionHandler<TestState, TestActions>;
+  onRender: (value: { counter: number; userName: string }) => void;
+};
+
+const ObjectSelectorConsumer = ({ createStateHandler, onRender }: ObjectSelectorConsumerProps) => {
+  const stateHandler = useStateHandler(createStateHandler, []);
+  const [summary] = useStateSubscription(stateHandler, (state) => ({
+    counter: state.counter,
+    userName: state.user.name,
+  }));
+
+  onRender(summary);
+
+  return <span>{summary.userName}</span>;
+};
+
 type StrictModeMirrorFactoryConsumerProps = {
   createStateHandler: () => StateSubscriptionHandler<CounterMirrorState, CounterMirrorActions>;
   onRender: (count: number) => void;
@@ -409,7 +429,7 @@ describe('Selector hooks', () => {
     expect(createStateHandler).toHaveBeenCalledTimes(1);
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     await act(async () => {
@@ -434,7 +454,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 +499,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 +511,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 +537,9 @@ describe('Selector hooks', () => {
     const renderSpy = jest.fn();
 
     act(() => {
-      root.render(<FactoryShortcutConsumer createStateHandler={createStateHandler} onRender={renderSpy} />);
+      root.render(
+        <FactoryShortcutConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+      );
     });
 
     act(() => {
@@ -564,6 +586,55 @@ describe('Selector hooks', () => {
     expect(renderSpy).toHaveBeenCalledTimes(2);
   });
 
+  it('useStateSubscription should cache object selector snapshots within one store version', () => {
+    let stateHandler: TestStateHandler | null = null;
+    const createStateHandler = jest.fn(() => {
+      if (!stateHandler) {
+        stateHandler = new TestStateHandler({
+          user: { name: 'Ada' },
+          counter: 0,
+        });
+      }
+
+      return stateHandler;
+    });
+    const renderSpy = jest.fn();
+
+    expect(() => {
+      act(() => {
+        root.render(
+          <ObjectSelectorConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+        );
+      });
+    }).not.toThrow();
+
+    expect(renderSpy).toHaveBeenCalledTimes(1);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 0,
+      userName: 'Ada',
+    });
+
+    act(() => {
+      stateHandler!.getActions().increment();
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(2);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 1,
+      userName: 'Ada',
+    });
+
+    act(() => {
+      stateHandler!.getActions().setName('Grace');
+    });
+
+    expect(renderSpy).toHaveBeenCalledTimes(3);
+    expect(renderSpy).toHaveBeenLastCalledWith({
+      counter: 1,
+      userName: 'Grace',
+    });
+  });
+
   it('useStateSubscription should return full snapshot when no selector is provided', () => {
     let stateHandler: TestStateHandler | null = null;
     const createStateHandler = jest.fn(() => {
@@ -577,7 +648,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 +665,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 +682,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 +718,7 @@ describe('Selector hooks', () => {
     expect(stateHandler.destroy).not.toHaveBeenCalled();
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(stateHandler.destroy).toHaveBeenCalledTimes(1);
@@ -683,7 +756,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 +768,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 +783,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 +796,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 +804,7 @@ describe('Selector hooks', () => {
     });
 
     act(() => {
-      root.render(<></>);
+      root.render(<React.Fragment />);
     });
 
     expect(firstHandler.destroy).not.toHaveBeenCalled();
@@ -764,7 +835,10 @@ describe('Selector hooks', () => {
     act(() => {
       root.render(
         <React.StrictMode>
-          <StrictModeMirrorFactoryConsumer createStateHandler={createStateHandler} onRender={renderSpy} />
+          <StrictModeMirrorFactoryConsumer
+            createStateHandler={createStateHandler}
+            onRender={renderSpy}
+          />
         </React.StrictMode>
       );
     });