@veams/status-quo 1.11.0 → 1.12.0

package/dist/store/base-state-handler.d.ts

@@ -22,6 +22,8 @@ type ManagedSubscription = {
 export declare abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler<S, A> {
     protected readonly initialState: S;
     protected devTools: DevTools | null;
+    private connectCount;
+    private isConnected;
     subscriptions: ManagedSubscription[];
     namedSubscriptions: Map<string, ManagedSubscription>;
     /**
@@ -49,10 +51,30 @@ export declare abstract class BaseStateHandler<S, A> implements StateSubscriptio
      * Also sends the update to DevTools if enabled.
      */
     setState(newState: Partial<S>, actionName?: string): void;
+    /**
+     * Starts external effects for this handler.
+     */
+    connect(): void;
+    /**
+     * Stops external effects once all connected consumers have disconnected.
+     */
+    disconnect(): void;
     /**
      * Cleans up all active subscriptions when the handler is destroyed.
      */
     destroy(): void;
+    /**
+     * Optional hook for subclasses that need to start external effects.
+     */
+    protected onConnect(): void;
+    /**
+     * Optional hook for subclasses that need to stop external effects.
+     */
+    protected onDisconnect(): void;
+    /**
+     * Clears all subscriptions managed through this base handler.
+     */
+    protected clearManagedSubscriptions(): void;
     protected abstract getStateValue(): S;
     protected abstract setStateValue(nextState: S): void;
     /**

package/dist/store/base-state-handler.js

@@ -28,6 +28,10 @@ export class BaseStateHandler {
     initialState;
     // Holds the Redux DevTools instance if enabled.
     devTools = null;
+    // Tracks mounted consumers that have connected this handler.
+    connectCount = 0;
+    // Prevents duplicate side effects while the handler is already connected.
+    isConnected = false;
     // Keeps track of active subscriptions to allow for cleanup.
     subscriptions = [];
     // Tracks keyed subscriptions so handlers can replace them by name.
@@ -91,10 +95,82 @@ export class BaseStateHandler {
         // Notify DevTools of the state change.
         this.devTools?.send(actionName, nextState);
     }
+    /**
+     * Starts external effects for this handler.
+     */
+    connect() {
+        const previousConnectCount = this.connectCount;
+        this.connectCount += 1;
+        if (this.isConnected) {
+            return;
+        }
+        this.isConnected = true;
+        try {
+            this.onConnect();
+        }
+        catch (error) {
+            this.connectCount = previousConnectCount;
+            this.isConnected = false;
+            this.clearManagedSubscriptions();
+            throw error;
+        }
+    }
+    /**
+     * Stops external effects once all connected consumers have disconnected.
+     */
+    disconnect() {
+        if (this.connectCount === 0) {
+            return;
+        }
+        this.connectCount -= 1;
+        if (this.connectCount > 0) {
+            return;
+        }
+        if (!this.isConnected) {
+            this.clearManagedSubscriptions();
+            return;
+        }
+        try {
+            this.onDisconnect();
+        }
+        finally {
+            this.isConnected = false;
+            this.clearManagedSubscriptions();
+        }
+    }
     /**
      * Cleans up all active subscriptions when the handler is destroyed.
      */
     destroy() {
+        this.connectCount = 0;
+        if (!this.isConnected) {
+            this.clearManagedSubscriptions();
+            return;
+        }
+        try {
+            this.onDisconnect();
+        }
+        finally {
+            this.isConnected = false;
+            this.clearManagedSubscriptions();
+        }
+    }
+    /**
+     * Optional hook for subclasses that need to start external effects.
+     */
+    onConnect() {
+        // Optional override.
+    }
+    /**
+     * Optional hook for subclasses that need to stop external effects.
+     */
+    onDisconnect() {
+        // Optional override.
+    }
+    /**
+     * Clears all subscriptions managed through this base handler.
+     */
+    clearManagedSubscriptions() {
         const subscriptions = [...this.subscriptions];
         const namedSubscriptions = [...this.namedSubscriptions.values()];
         this.subscriptions = [];

package/dist/store/base-state-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"base-state-handler.js","sourceRoot":"","sources":["../../src/store/base-state-handler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base-state-handler.js","sourceRoot":"","sources":["../../src/store/base-state-handler.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAwB9C;;GAEG;AACH,MAAM,gBAAgB,GAAG;IACvB,KAAK,EAAE,IAAI,EAAE,0CAA0C;IACvD,IAAI,EAAE,IAAI,EAAE,2BAA2B;IACvC,OAAO,EAAE,KAAK,EAAE,kDAAkD;IAClE,MAAM,EAAE,IAAI,EAAE,qCAAqC;IACnD,MAAM,EAAE,QAAQ,EAAE,2BAA2B;IAC7C,IAAI,EAAE,IAAI,EAAE,oCAAoC;IAChD,IAAI,EAAE,IAAI,EAAE,mCAAmC;IAC/C,OAAO,EAAE,IAAI,EAAE,4BAA4B;IAC3C,QAAQ,EAAE,KAAK,EAAE,kDAAkD;IACnE,IAAI,EAAE,KAAK,EAAE,yBAAyB;CAC9B,CAAC;AAEX;;;GAGG;AACH,MAAM,OAAgB,gBAAgB;IACpC,uDAAuD;IACpC,YAAY,CAAI;IACnC,gDAAgD;IACtC,QAAQ,GAAoB,IAAI,CAAC;IAE3C,6DAA6D;IACrD,YAAY,GAAG,CAAC,CAAC;IACzB,0EAA0E;IAClE,WAAW,GAAG,KAAK,CAAC;IAE5B,4DAA4D;IAC5D,aAAa,GAA0B,EAAE,CAAC;IAC1C,mEAAmE;IACnE,kBAAkB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAE5D;;OAEG;IACH,YAAsB,YAAe;QACnC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IAED;;OAEG;IACO,YAAY,CAAC,eAAiC;QACtD,4CAA4C;QAC5C,MAAM,eAAe,GAAG,sBAAsB,CAAC,eAAe,CAAC,CAAC;QAEhE,sCAAsC;QACtC,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;YAC7B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACrB,OAAO;QACT,CAAC;QAED,qDAAqD;QACrD,MAAM,SAAS,GAAG,eAAe,EAAE,SAAS,IAAI,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAE5E,2CAA2C;QAC3C,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE;YAC9C,IAAI,EAAE,SAAS;YACf,UAAU,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC;YACxD,cAAc,EAAE,IAAI,CAAC,UAAU,EAAE;YACjC,QAAQ,EAAE,gBAAgB;SAC3B,CAAC,CAAC;QAEH,8EAA8E;QAC9E,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,OAAO,IAAI,CAAC,aAAa,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,EAAE,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,QAAoB,EAAE,UAAU,GAAG,QAAQ;QAClD,kDAAkD;QAClD,MAAM,SAAS,GAAG,EAAE,GAAG,eAAe,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxF,iEAAiE;QACjE,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC9B,uCAAuC;QACvC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,OAAO;QACL,MAAM,oBAAoB,GAAG,IAAI,CAAC,YAAY,CAAC;QAC/C,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QAEvB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAExB,IAAI,CAAC;YACH,IAAI,CAAC,SAAS,EAAE,CAAC;QACnB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,YAAY,GAAG,oBAAoB,CAAC;YACzC,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;YACzB,IAAI,CAAC,yBAAyB,EAAE,CAAC;YACjC,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,IAAI,CAAC,YAAY,KAAK,CAAC,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC;QAEvB,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YAC1B,OAAO;QACT,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,yBAAyB,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;YACzB,IAAI,CAAC,yBAAyB,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QAEtB,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,yBAAyB,EAAE,CAAC;YACjC,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,IAAI,CAAC,YAAY,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC;YACzB,IAAI,CAAC,yBAAyB,EAAE,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;OAEG;IACO,SAAS;QACjB,qBAAqB;IACvB,CAAC;IAED;;OAEG;IACO,YAAY;QACpB,qBAAqB;IACvB,CAAC;IAED;;OAEG;IACO,yBAAyB;QACjC,MAAM,aAAa,GAAG,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;QAC9C,MAAM,kBAAkB,GAAG,CAAC,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC;QAEjE,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,kBAAkB,CAAC,KAAK,EAAE,CAAC;QAEhC,kEAAkE;QAClE,aAAa,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;QACpE,kBAAkB,CAAC,OAAO,CAAC,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IAC3E,CAAC;IAMD;;OAEG;IACO,oBAAoB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,OAAO,CAAC;IAC1C,CAAC;IAyBS,gBAAgB,CACxB,yBAAmD,EACnD,iBAA2D,EAC3D,kBAA8D,EAC9D,iBAAsD,EACtD,UAA2B,MAAM,CAAC,EAAE;QAEpC,MAAM,mBAAmB,GAAG,OAAO,yBAAyB,KAAK,QAAQ,CAAC;QAC1E,MAAM,gBAAgB,GAAG,mBAAmB,CAAC,CAAC,CAAC,yBAAyB,CAAC,CAAC,CAAC,IAAI,CAAC;QAChF,MAAM,OAAO,GAAG,CACd,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,yBAAyB,CACjD,CAAC;QACrB,MAAM,QAAQ,GAAG,CACf,mBAAmB,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,iBAAiB,CACrC,CAAC;QAC1B,MAAM,QAAQ,GAAG,CACf,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,CAC7B,CAAC;QAClC,MAAM,UAAU,GAAG,CACjB,mBAAmB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,iBAAiB,IAAI,MAAM,CAAC,EAAE,CAAC,CAC9C,CAAC;QAErB,oDAAoD;QACpD,MAAM,UAAU,GAAG,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAQ,EAAE,EAAE,CAAC,KAAuB,CAAC,CAAC,CAAC;QACzE,oEAAoE;QACpE,MAAM,aAAa,GAAG,mBAAmB,EAAO,CAAC;QACjD,mFAAmF;QACnF,IAAI,iBAAiB,GAAG,KAAK,CAAC;QAE9B,sEAAsE;QACtE,MAAM,mBAAmB,GAAG,CAAC,KAAQ,EAAE,EAAE;YACvC,iBAAiB,GAAG,IAAI,CAAC;YACzB,mEAAmE;YACnE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,GAAG,eAAe,CAC1D,aAAa,EACb,KAAK,EACL,UAAU,EACV,UAAU,CACX,CAAC;YAEF,2DAA2D;YAC3D,IAAI,CAAC,UAAU,EAAE,CAAC;gBAChB,OAAO;YACT,CAAC;YAED,QAAQ,CAAC,aAAa,CAAC,CAAC;QAC1B,CAAC,CAAC;QAEF,IAAI,gBAAgB,EAAE,CAAC;YACrB,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,CAAC;QAC/D,CAAC;QAED,oCAAoC;QACpC,MAAM,YAAY,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,SAAS,CAAC,mBAAmB,CAAC,EAAE,CAAC;QAE7E,IAAI,gBAAgB,EAAE,CAAC;YACrB,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,gBAAgB,EAAE,YAAY,CAAC,CAAC;QAC9D,CAAC;aAAM,CAAC;YACN,4CAA4C;YAC5C,IAAI,CAAC,aAAa,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,IAAI,EAAE,CAAC,EAAE,YAAY,CAAC,CAAC;QACrE,CAAC;QAED,gGAAgG;QAChG,IAAI,OAAO,CAAC,WAAW,IAAI,CAAC,iBAAiB;YAAE,mBAAmB,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC5F,CAAC;IAOD;;OAEG;IACK,oBAAoB,GAAG,CAAC,OAAuB,EAAE,EAAE;QACzD,iEAAiE;QACjE,IAAI,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAChC,OAAO;QACT,CAAC;QAED,QAAQ,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAC7B,qCAAqC;YACrC,KAAK,OAAO;gBACV,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;gBAC3C,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;gBAC5C,MAAM;YAER,wCAAwC;YACxC,KAAK,QAAQ;gBACX,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACpC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACrC,MAAM;YAER,8BAA8B;YAC9B,KAAK,eAAe,CAAC;YACrB,KAAK,gBAAgB;gBACnB,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAM,CAAC,CAAC;gBACnD,MAAM;YAER;gBACE,MAAM;QACV,CAAC;IACH,CAAC,CAAC;CACH"}

package/dist/types/types.d.ts

@@ -10,6 +10,8 @@
 export interface StateSubscriptionHandler<V, A> {
     subscribe(listener: () => void): () => void;
     subscribe(listener: (value: V) => void): () => void;
+    connect?: () => void;
+    disconnect?: () => void;
     getSnapshot: () => V;
     destroy: () => void;
     getInitialState: () => V;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veams/status-quo",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "The manager to rule states in frontend.",
   "main": "dist/index.js",
   "module": "dist/index.js",

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

@@ -13,7 +13,7 @@ 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;
 }
 
@@ -106,6 +106,11 @@ class TestStateHandler implements StateSubscriptionHandler<TestState, TestAction
   }
 }
 
+class LifecycleTestStateHandler extends TestStateHandler {
+  connect = jest.fn();
+  disconnect = jest.fn();
+}
+
 class CounterStateHandler implements StateSubscriptionHandler<CounterState, CounterActions> {
   private readonly initialState: CounterState;
   private state: CounterState;
@@ -677,6 +682,160 @@ describe('Selector hooks', () => {
     });
   });
 
+  it('useStateSubscription should connect after commit and defer disconnect cleanup', async () => {
+    const stateHandler = new LifecycleTestStateHandler({
+      user: { name: 'Ada' },
+      counter: 0,
+    });
+    const createStateHandler = jest.fn(() => stateHandler);
+    const renderConnectCallCounts: number[] = [];
+    const renderSpy = jest.fn(() => {
+      renderConnectCallCounts.push(stateHandler.connect.mock.calls.length);
+    });
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
+
+    act(() => {
+      root.render(
+        <FullSubscriptionConsumer
+          createStateHandler={createStateHandler}
+          onRender={renderSpy}
+          onActionsReady={actionsReadySpy}
+        />
+      );
+    });
+
+    expect(renderConnectCallCounts).toStrictEqual([0]);
+    expect(stateHandler.connect).toHaveBeenCalledTimes(1);
+    expect(stateHandler.disconnect).not.toHaveBeenCalled();
+    expect(stateHandler.destroy).not.toHaveBeenCalled();
+
+    act(() => {
+      root.render(<React.Fragment />);
+    });
+
+    expect(stateHandler.disconnect).not.toHaveBeenCalled();
+    expect(stateHandler.destroy).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    });
+
+    expect(stateHandler.disconnect).toHaveBeenCalledTimes(1);
+    expect(stateHandler.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('useStateSubscription should keep the connection through immediate resubscription', async () => {
+    const stateHandler = new LifecycleTestStateHandler({
+      user: { name: 'Ada' },
+      counter: 0,
+    });
+    const createStateHandler = jest.fn(() => stateHandler);
+    const renderSpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
+
+    act(() => {
+      root.render(
+        <FullSubscriptionConsumer
+          createStateHandler={createStateHandler}
+          onRender={renderSpy}
+          onActionsReady={actionsReadySpy}
+        />
+      );
+    });
+
+    act(() => {
+      root.render(<React.Fragment />);
+    });
+
+    act(() => {
+      root.render(
+        <FullSubscriptionConsumer
+          createStateHandler={createStateHandler}
+          onRender={renderSpy}
+          onActionsReady={actionsReadySpy}
+        />
+      );
+    });
+
+    await act(async () => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    });
+
+    expect(stateHandler.connect).toHaveBeenCalledTimes(1);
+    expect(stateHandler.disconnect).not.toHaveBeenCalled();
+    expect(stateHandler.destroy).not.toHaveBeenCalled();
+
+    act(() => {
+      root.render(<React.Fragment />);
+    });
+
+    await act(async () => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    });
+
+    expect(stateHandler.disconnect).toHaveBeenCalledTimes(1);
+    expect(stateHandler.destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('useStateSubscription should disconnect only after the last consumer unsubscribes', async () => {
+    const stateHandler = new LifecycleTestStateHandler({
+      user: { name: 'Ada' },
+      counter: 0,
+    });
+    const createStateHandler = jest.fn(() => stateHandler);
+    const firstRenderSpy = jest.fn();
+    const secondRenderSpy = jest.fn();
+    const actionsReadySpy = jest.fn<void, [TestActions]>();
+    const Consumers = ({ showSecond }: { showSecond: boolean }) => (
+      <React.Fragment>
+        <FullSubscriptionConsumer
+          createStateHandler={createStateHandler}
+          onRender={firstRenderSpy}
+          onActionsReady={actionsReadySpy}
+        />
+        {showSecond && (
+          <FullSubscriptionConsumer
+            createStateHandler={createStateHandler}
+            onRender={secondRenderSpy}
+            onActionsReady={actionsReadySpy}
+          />
+        )}
+      </React.Fragment>
+    );
+
+    act(() => {
+      root.render(<Consumers showSecond />);
+    });
+
+    expect(stateHandler.connect).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      root.render(<Consumers showSecond={false} />);
+    });
+
+    expect(stateHandler.disconnect).not.toHaveBeenCalled();
+    expect(stateHandler.destroy).not.toHaveBeenCalled();
+
+    act(() => {
+      root.render(<React.Fragment />);
+    });
+
+    await act(async () => {
+      await new Promise((resolve) => {
+        setTimeout(resolve, 0);
+      });
+    });
+
+    expect(stateHandler.disconnect).toHaveBeenCalledTimes(1);
+    expect(stateHandler.destroy).toHaveBeenCalledTimes(1);
+  });
+
   it('useStateSingleton selector should keep singleton alive while consumers exist', () => {
     const stateHandler = new TestStateHandler({
       user: { name: 'Ada' },

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

@@ -20,12 +20,12 @@ type Listener = () => void;
 type SharedStateSubscriptionHandler = StateSubscriptionHandler<unknown, unknown>;
 
 /**
- * Tracks the reference count and deferred destruction status of a state handler.
+ * Tracks the reference count and deferred lifecycle cleanup status of a state handler.
  */
-type DeferredDestroy = {
+type DeferredLifecycle = {
   // Number of active consumers of the state handler.
   refCount: number;
-  // ID of the timeout for deferred destruction.
+  // ID of the timeout for deferred disconnect/destruction.
   timeoutId: ReturnType<typeof setTimeout> | null;
 };
 
@@ -51,18 +51,18 @@ type ServerSnapshotCacheEntry<Source, Selected> = {
   sourceSnapshot: Source;
 };
 
-// Global map to track deferred destruction status for each state handler instance.
-const deferredDestroyMap = new WeakMap<SharedStateSubscriptionHandler, DeferredDestroy>();
+// Global map to track deferred lifecycle status for each state handler instance.
+const deferredLifecycleMap = new WeakMap<SharedStateSubscriptionHandler, DeferredLifecycle>();
 
 /**
- * Returns the deferred destruction status for a given state handler instance.
+ * Returns the deferred lifecycle status for a given state handler instance.
  * Initializes the status if it does not already exist.
  */
-function getDeferredDestroyState(
+function getDeferredLifecycleState(
   stateSubscriptionHandler: SharedStateSubscriptionHandler
-): DeferredDestroy {
+): DeferredLifecycle {
   // Retrieve the existing status from the map.
-  const existingState = deferredDestroyMap.get(stateSubscriptionHandler);
+  const existingState = deferredLifecycleMap.get(stateSubscriptionHandler);
 
   // If status already exists, return it.
   if (existingState) {
@@ -70,12 +70,12 @@ function getDeferredDestroyState(
   }
 
   // Create and store a new status for the handler.
-  const nextState: DeferredDestroy = {
+  const nextState: DeferredLifecycle = {
     refCount: 0,
     timeoutId: null,
   };
 
-  deferredDestroyMap.set(stateSubscriptionHandler, nextState);
+  deferredLifecycleMap.set(stateSubscriptionHandler, nextState);
 
   return nextState;
 }
@@ -113,17 +113,20 @@ export function useStateSubscriptionSelector<V, A, Sel>(
   // Subscription function to be used by useSyncExternalStore.
   const subscribe = useCallback(
     (listener: Listener) => {
-      // Access the deferred destruction status for this handler.
+      // Access the deferred lifecycle status for this handler.
       const sharedStateSubscriptionHandler =
         stateSubscriptionHandler as unknown as SharedStateSubscriptionHandler;
-      const deferredDestroyState = getDeferredDestroyState(sharedStateSubscriptionHandler);
+      const deferredLifecycleState = getDeferredLifecycleState(sharedStateSubscriptionHandler);
+      const hadPendingCleanup = deferredLifecycleState.timeoutId !== null;
+      const wasIdle = deferredLifecycleState.refCount === 0;
+
       // Increment the consumer reference count.
-      deferredDestroyState.refCount += 1;
+      deferredLifecycleState.refCount += 1;
 
-      // If a pending destruction timeout is scheduled, cancel it.
-      if (deferredDestroyState.timeoutId) {
-        clearTimeout(deferredDestroyState.timeoutId);
-        deferredDestroyState.timeoutId = null;
+      // If a pending cleanup timeout is scheduled, cancel it.
+      if (deferredLifecycleState.timeoutId) {
+        clearTimeout(deferredLifecycleState.timeoutId);
+        deferredLifecycleState.timeoutId = null;
       }
 
       // Subscribe to the state handler.
@@ -135,51 +138,62 @@ export function useStateSubscriptionSelector<V, A, Sel>(
         listener();
       });
 
+      if (wasIdle && !hadPendingCleanup) {
+        stateSubscriptionHandler.connect?.();
+      }
+
       // Return an unsubscribe function to be called by React.
       return () => {
         // Execute the handler's unsubscribe method.
         unsubscribe();
 
-        // If automatic cleanup is disabled, stop here.
-        if (!destroyOnCleanup) {
-          return;
-        }
-
-        // Retrieve the current destruction status.
-        const activeDeferredDestroyState = deferredDestroyMap.get(sharedStateSubscriptionHandler);
+        // Retrieve the current lifecycle status.
+        const activeDeferredLifecycleState = deferredLifecycleMap.get(
+          sharedStateSubscriptionHandler
+        );
 
         // If no status is found, stop here.
-        if (!activeDeferredDestroyState) {
+        if (!activeDeferredLifecycleState) {
           return;
         }
 
         // Decrement the consumer reference count.
-        activeDeferredDestroyState.refCount -= 1;
+        activeDeferredLifecycleState.refCount -= 1;
 
-        // If there are still active consumers, do not destroy the handler.
-        if (activeDeferredDestroyState.refCount > 0) {
+        // If there are still active consumers, keep the handler connected.
+        if (activeDeferredLifecycleState.refCount > 0) {
           return;
         }
 
         // Reset the reference count to zero.
-        activeDeferredDestroyState.refCount = 0;
-        // Schedule deferred destruction to allow for potential immediate re-subscriptions.
-        activeDeferredDestroyState.timeoutId = setTimeout(() => {
+        activeDeferredLifecycleState.refCount = 0;
+        // Schedule deferred cleanup to allow for potential immediate re-subscriptions.
+        activeDeferredLifecycleState.timeoutId = setTimeout(() => {
           // Check if the handler still has no consumers after the timeout.
-          const pendingDeferredDestroyState = deferredDestroyMap.get(
+          const pendingDeferredLifecycleState = deferredLifecycleMap.get(
             sharedStateSubscriptionHandler
           );
 
-          // If consumers have reappeared, do not destroy the handler.
-          if (!pendingDeferredDestroyState || pendingDeferredDestroyState.refCount > 0) {
+          // If consumers have reappeared, keep the handler connected.
+          if (!pendingDeferredLifecycleState || pendingDeferredLifecycleState.refCount > 0) {
             return;
           }
 
-          // Clear the pending timeout and destroy the state handler.
-          pendingDeferredDestroyState.timeoutId = null;
-          stateSubscriptionHandler.destroy();
-          // Remove the status from the global map.
-          deferredDestroyMap.delete(sharedStateSubscriptionHandler);
+          // Clear the pending timeout and disconnect the state handler.
+          pendingDeferredLifecycleState.timeoutId = null;
+
+          try {
+            stateSubscriptionHandler.disconnect?.();
+          } finally {
+            if (destroyOnCleanup) {
+              try {
+                stateSubscriptionHandler.destroy();
+              } finally {
+                // Remove the status from the global map after final destruction.
+                deferredLifecycleMap.delete(sharedStateSubscriptionHandler);
+              }
+            }
+          }
         }, 0);
       };
     },

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

@@ -51,6 +51,7 @@ type CounterBucketSelection = { bucket: number };
 type CounterBucketState = { bucket: number };
 type SetState = { openItems: Set<string> };
 type SetActions = { toggle: (id: string) => void };
+type NoopActions = { noop: () => void };
 type CounterSubscribable = {
   subscribe: (listener: (value: CounterState) => void) => () => void;
   getSnapshot: () => CounterState;
@@ -200,6 +201,37 @@ class SetNativeStateHandler extends NativeStateHandler<SetState, SetActions> {
   }
 }
 
+class LifecycleNativeStateHandler extends NativeStateHandler<CounterState, NoopActions> {
+  constructor(
+    private readonly onConnectSpy: () => void,
+    private readonly onDisconnectSpy: () => void
+  ) {
+    super({
+      initialState: {
+        count: 0,
+      },
+    });
+  }
+
+  trackSubscription(subscription: { unsubscribe: () => void }) {
+    this.subscriptions = [...this.subscriptions, subscription];
+  }
+
+  protected override onConnect(): void {
+    this.onConnectSpy();
+  }
+
+  protected override onDisconnect(): void {
+    this.onDisconnectSpy();
+  }
+
+  getActions(): NoopActions {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
 function createCounterSubscribable(initialCount: number) {
   let listener: ((value: CounterState) => void) | null = null;
   const unsubscribe = jest.fn(() => {
@@ -269,6 +301,54 @@ describe('Native State Handler', () => {
     expect(spy).toHaveBeenCalledTimes(1);
   });
 
+  it('should connect and disconnect side effects with reference counting', () => {
+    const onConnectSpy = jest.fn();
+    const onDisconnectSpy = jest.fn();
+    const handler = new LifecycleNativeStateHandler(onConnectSpy, onDisconnectSpy);
+
+    expect(handler.getSnapshot()).toStrictEqual({ count: 0 });
+    expect(onConnectSpy).not.toHaveBeenCalled();
+
+    handler.connect();
+    handler.connect();
+    handler.disconnect();
+
+    expect(onConnectSpy).toHaveBeenCalledTimes(1);
+    expect(onDisconnectSpy).not.toHaveBeenCalled();
+
+    handler.disconnect();
+
+    expect(onDisconnectSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('should clear managed subscriptions on disconnect', () => {
+    const handler = new LifecycleNativeStateHandler(jest.fn(), jest.fn());
+    const unsubscribeSpy = jest.fn();
+
+    handler.trackSubscription({ unsubscribe: unsubscribeSpy });
+    handler.connect();
+    handler.disconnect();
+
+    expect(unsubscribeSpy).toHaveBeenCalledTimes(1);
+    expect(handler.subscriptions).toStrictEqual([]);
+  });
+
+  it('should disconnect and clear managed subscriptions on destroy', () => {
+    const onDisconnectSpy = jest.fn();
+    const handler = new LifecycleNativeStateHandler(jest.fn(), onDisconnectSpy);
+    const unsubscribeSpy = jest.fn();
+
+    handler.trackSubscription({ unsubscribe: unsubscribeSpy });
+    handler.connect();
+    handler.connect();
+
+    handler.destroy();
+    handler.disconnect();
+
+    expect(onDisconnectSpy).toHaveBeenCalledTimes(1);
+    expect(unsubscribeSpy).toHaveBeenCalledTimes(1);
+  });
+
   it('should call subscriber when state has changed and also on initial subscribe', () => {
     const spy = jest.fn();
     const unsubscribe = stateHandler.subscribe(spy);