@veams/status-quo 1.3.2 → 1.5.0

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

@@ -12,13 +12,13 @@ type SignalStateHandlerProps<S> = {
         useDistinctUntilChanged?: boolean;
     };
 };
-type Listener = () => void;
 export declare abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
     private readonly state;
     private readonly distinctOptions;
     protected constructor({ initialState, options }: SignalStateHandlerProps<S>);
     getSignal(): Signal<S>;
-    subscribe(listener: Listener): () => void;
+    subscribe(listener: () => void): () => void;
+    subscribe(listener: (value: S) => void): () => void;
     protected getStateValue(): S;
     protected setStateValue(nextState: S): void;
 }

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

@@ -20,6 +20,7 @@ export class SignalStateHandler extends BaseStateHandler {
             if (!initialized) {
                 initialized = true;
                 previousSnapshot = nextState;
+                listener(nextState);
                 return;
             }
             if (this.distinctOptions.enabled && this.distinctOptions.comparator(previousSnapshot, nextState)) {
@@ -27,7 +28,7 @@ export class SignalStateHandler extends BaseStateHandler {
                 return;
             }
             previousSnapshot = nextState;
-            listener();
+            listener(nextState);
         });
     }
     getStateValue() {

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

@@ -1 +1 @@
-{"version":3,"file":"signal-state-handler.js","sourceRoot":"","sources":["../../src/store/signal-state-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAmBxE,MAAM,OAAgB,kBAAyB,SAAQ,gBAAsB;IAC1D,KAAK,CAAY;IACjB,eAAe,CAA+C;IAE/E,YAAsB,EAAE,YAAY,EAAE,OAAO,EAA8B;QACzE,KAAK,CAAC,YAAY,CAAC,CAAC;QAEpB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,sBAAsB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC;QACnG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,SAAS,CAAC,QAAkB;QAC1B,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,IAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAExC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE;YACxC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,WAAW,GAAG,IAAI,CAAC;gBACnB,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,gBAAgB,EAAE,SAAS,CAAC,EAAE,CAAC;gBACjG,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,gBAAgB,GAAG,SAAS,CAAC;YAC7B,QAAQ,EAAE,CAAC;QACb,CAAC,CAAC,CAAC;IACL,CAAC;IAES,aAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAES,aAAa,CAAC,SAAY;QAClC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAC/B,CAAC;CACF"}
+{"version":3,"file":"signal-state-handler.js","sourceRoot":"","sources":["../../src/store/signal-state-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAE9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAiBxE,MAAM,OAAgB,kBAAyB,SAAQ,gBAAsB;IAC1D,KAAK,CAAY;IACjB,eAAe,CAA+C;IAE/E,YAAsB,EAAE,YAAY,EAAE,OAAO,EAA8B;QACzE,KAAK,CAAC,YAAY,CAAC,CAAC;QAEpB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAI,YAAY,CAAC,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,sBAAsB,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC;QACnG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAID,SAAS,CAAC,QAA4B;QACpC,IAAI,WAAW,GAAG,KAAK,CAAC;QACxB,IAAI,gBAAgB,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;QAExC,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,EAAE;YACxC,IAAI,CAAC,WAAW,EAAE,CAAC;gBACjB,WAAW,GAAG,IAAI,CAAC;gBACnB,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;gBACpB,OAAO;YACT,CAAC;YAED,IAAI,IAAI,CAAC,eAAe,CAAC,OAAO,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,gBAAgB,EAAE,SAAS,CAAC,EAAE,CAAC;gBACjG,gBAAgB,GAAG,SAAS,CAAC;gBAC7B,OAAO;YACT,CAAC;YAED,gBAAgB,GAAG,SAAS,CAAC;YAC7B,QAAQ,CAAC,SAAS,CAAC,CAAC;QACtB,CAAC,CAAC,CAAC;IACL,CAAC;IAES,aAAa;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAES,aAAa,CAAC,SAAY;QAClC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,SAAS,CAAC;IAC/B,CAAC;CACF"}

package/dist/types/types.d.ts

@@ -1,5 +1,6 @@
 export interface StateSubscriptionHandler<V, A> {
-    subscribe: (listener: () => void) => () => void;
+    subscribe(listener: () => void): () => void;
+    subscribe(listener: (value: V) => void): () => void;
     getSnapshot: () => V;
     destroy: () => void;
     getInitialState: () => V;

package/dist/utils/selector-cache.d.ts

@@ -0,0 +1,13 @@
+export type Selector<Value, Selected> = (value: Value) => Selected;
+export type EqualityFn<Selected> = (current: Selected, next: Selected) => boolean;
+type SelectorCache<Selected> = {
+    hasValue: boolean;
+    value: Selected | undefined;
+};
+type SelectionResult<Selected> = {
+    value: Selected;
+    hasChanged: boolean;
+};
+export declare function createSelectorCache<Selected>(): SelectorCache<Selected>;
+export declare function selectWithCache<Value, Selected>(selectorCache: SelectorCache<Selected>, value: Value, selector: Selector<Value, Selected>, isEqual?: EqualityFn<Selected>): SelectionResult<Selected>;
+export {};

package/dist/utils/selector-cache.js

@@ -0,0 +1,22 @@
+export function createSelectorCache() {
+    return {
+        hasValue: false,
+        value: undefined,
+    };
+}
+export function selectWithCache(selectorCache, value, selector, isEqual = Object.is) {
+    const nextSelection = selector(value);
+    if (selectorCache.hasValue && isEqual(selectorCache.value, nextSelection)) {
+        return {
+            value: selectorCache.value,
+            hasChanged: false,
+        };
+    }
+    selectorCache.hasValue = true;
+    selectorCache.value = nextSelection;
+    return {
+        value: nextSelection,
+        hasChanged: true,
+    };
+}
+//# sourceMappingURL=selector-cache.js.map

package/dist/utils/selector-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"selector-cache.js","sourceRoot":"","sources":["../../src/utils/selector-cache.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,KAAK,EAAE,SAAS;KACjB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,aAAsC,EACtC,KAAY,EACZ,QAAmC,EACnC,UAAgC,MAAM,CAAC,EAAE;IAEzC,MAAM,aAAa,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEtC,IAAI,aAAa,CAAC,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC,KAAiB,EAAE,aAAa,CAAC,EAAE,CAAC;QACtF,OAAO;YACL,KAAK,EAAE,aAAa,CAAC,KAAiB;YACtC,UAAU,EAAE,KAAK;SAClB,CAAC;IACJ,CAAC;IAED,aAAa,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC9B,aAAa,CAAC,KAAK,GAAG,aAAa,CAAC;IAEpC,OAAO;QACL,KAAK,EAAE,aAAa;QACpB,UAAU,EAAE,IAAI;KACjB,CAAC;AACJ,CAAC"}

package/package.json

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

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

@@ -50,7 +50,7 @@ type CounterMirrorActions = {
 class TestStateHandler implements StateSubscriptionHandler<TestState, TestActions> {
   private readonly initialState: TestState;
   private state: TestState;
-  private readonly listeners = new Set<() => void>();
+  private readonly listeners = new Set<(value: TestState) => void>();
 
   destroy = jest.fn();
 
@@ -59,13 +59,16 @@ class TestStateHandler implements StateSubscriptionHandler<TestState, TestAction
     this.state = initialState;
   }
 
-  subscribe = (listener: () => void) => {
-    this.listeners.add(listener);
+  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(listener);
+      this.listeners.delete(typedListener);
     };
-  };
+  }
 
   getSnapshot = () => {
     return this.state;
@@ -100,14 +103,15 @@ class TestStateHandler implements StateSubscriptionHandler<TestState, TestAction
   };
 
   private emitStateChange() {
-    this.listeners.forEach((listener) => listener());
+    const nextState = this.state;
+    this.listeners.forEach((listener) => listener(nextState));
   }
 }
 
 class CounterStateHandler implements StateSubscriptionHandler<CounterState, CounterActions> {
   private readonly initialState: CounterState;
   private state: CounterState;
-  private readonly listeners = new Set<() => void>();
+  private readonly listeners = new Set<(value: CounterState) => void>();
 
   destroy = jest.fn();
 
@@ -116,13 +120,16 @@ class CounterStateHandler implements StateSubscriptionHandler<CounterState, Coun
     this.state = this.initialState;
   }
 
-  subscribe = (listener: () => void) => {
-    this.listeners.add(listener);
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: CounterState) => void): () => void;
+  subscribe(listener: ((value: CounterState) => void) | (() => void)) {
+    const typedListener = listener as (value: CounterState) => void;
+    this.listeners.add(typedListener);
 
     return () => {
-      this.listeners.delete(listener);
+      this.listeners.delete(typedListener);
     };
-  };
+  }
 
   getSnapshot = () => {
     return this.state;
@@ -139,7 +146,8 @@ class CounterStateHandler implements StateSubscriptionHandler<CounterState, Coun
           count: this.state.count + 1,
         };
 
-        this.listeners.forEach((listener) => listener());
+        const nextState = this.state;
+        this.listeners.forEach((listener) => listener(nextState));
       },
     };
   };
@@ -150,7 +158,7 @@ class CounterMirrorStateHandler
 {
   private readonly initialState: CounterMirrorState;
   private state: CounterMirrorState;
-  private readonly listeners = new Set<() => void>();
+  private readonly listeners = new Set<(value: CounterMirrorState) => void>();
   private readonly unsubscribeFromCounter: () => void;
 
   destroy = jest.fn(() => {
@@ -165,22 +173,25 @@ class CounterMirrorStateHandler
       mirroredCount: initialCounterState.count,
     };
     this.state = this.initialState;
-    this.unsubscribeFromCounter = counterStateHandler.subscribe(() => {
-      const nextCounterState = counterStateHandler.getSnapshot();
+    this.unsubscribeFromCounter = counterStateHandler.subscribe((nextCounterState: CounterState) => {
       this.state = {
         mirroredCount: nextCounterState.count,
       };
-      this.listeners.forEach((listener) => listener());
+      const nextMirrorState = this.state;
+      this.listeners.forEach((listener) => listener(nextMirrorState));
     });
   }
 
-  subscribe = (listener: () => void) => {
-    this.listeners.add(listener);
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: CounterMirrorState) => void): () => void;
+  subscribe(listener: ((value: CounterMirrorState) => void) | (() => void)) {
+    const typedListener = listener as (value: CounterMirrorState) => void;
+    this.listeners.add(typedListener);
 
     return () => {
-      this.listeners.delete(listener);
+      this.listeners.delete(typedListener);
     };
-  };
+  }
 
   getSnapshot = () => {
     return this.state;

package/src/hooks/__tests__/state-singleton.spec.tsx

@@ -31,7 +31,7 @@ const createStateHandler = (value: number): TestHandler => {
   const actions = { noop: jest.fn() };
 
   return {
-    subscribe: () => () => undefined,
+    subscribe: (_listener: (() => void) | ((value: TestState) => void)) => () => undefined,
     getSnapshot: () => snapshot,
     getInitialState: () => snapshot,
     getActions: () => actions,

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

@@ -1,14 +1,9 @@
 import { useCallback, useMemo, 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 SelectorCache<SelectedState> = {
-  hasValue: boolean;
-  value: SelectedState | undefined;
-};
-
-type SelectorFn<State, SelectedState> = (state: State) => SelectedState;
-type EqualityFn<SelectedState> = (current: SelectedState, next: SelectedState) => boolean;
 type Listener = () => void;
 type SharedStateSubscriptionHandler = StateSubscriptionHandler<unknown, unknown>;
 type DeferredDestroy = {
@@ -39,17 +34,11 @@ function getDeferredDestroyState(
 
 export function useStateSubscriptionSelector<V, A, Sel>(
   stateSubscriptionHandler: StateSubscriptionHandler<V, A>,
-  selector: SelectorFn<V, Sel>,
+  selector: Selector<V, Sel>,
   isEqual: EqualityFn<Sel> = Object.is,
   destroyOnCleanup = true
 ) {
-  const selectorCache = useMemo<SelectorCache<Sel>>(
-    () => ({
-      hasValue: false,
-      value: undefined,
-    }),
-    [stateSubscriptionHandler]
-  );
+  const selectorCache = useMemo(() => createSelectorCache<Sel>(), [stateSubscriptionHandler]);
 
   const subscribe = useCallback(
     (listener: Listener) => {
@@ -103,16 +92,7 @@ export function useStateSubscriptionSelector<V, A, Sel>(
 
   const selectSnapshot = useCallback(
     (snapshot: V) => {
-      const nextSelection = selector(snapshot);
-
-      if (selectorCache.hasValue && isEqual(selectorCache.value as Sel, nextSelection)) {
-        return selectorCache.value as Sel;
-      }
-
-      selectorCache.hasValue = true;
-      selectorCache.value = nextSelection;
-
-      return nextSelection;
+      return selectWithCache(selectorCache, snapshot, selector, isEqual).value;
     },
     [isEqual, selector, selectorCache]
   );

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

@@ -127,7 +127,7 @@ describe('Observable State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(2); // 1. test (first setter), 2. test2 (second setter)
+    expect(spy).toHaveBeenCalledTimes(3); // 1. initial, 2. test (first setter), 3. test2 (second setter)
   });
 
   it('should respect global distinct setup when disabled', () => {
@@ -146,7 +146,7 @@ describe('Observable State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveBeenCalledTimes(3);
   });
 
   it('should respect global custom distinct comparator from setupStatusQuo', () => {
@@ -167,7 +167,7 @@ describe('Observable State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledTimes(2);
   });
 
   it('should prefer per-handler distinct options over global setup', () => {
@@ -190,6 +190,6 @@ describe('Observable State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledTimes(2);
   });
 });

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

@@ -46,6 +46,8 @@ class TestSignalStateHandler extends SignalStateHandler<TestState, TestActions>
 
 type CounterState = { count: number };
 type CounterActions = { increase: () => void };
+type CounterBucketSelection = { bucket: number };
+type CounterBucketState = { bucket: number };
 
 class CounterSignalStateHandler extends SignalStateHandler<CounterState, CounterActions> {
   constructor(initialCount = 0) {
@@ -78,16 +80,49 @@ class CounterSignalBridgeStateHandler extends SignalStateHandler<CounterState, {
 
     const counterStateHandler = counterSingleton.getInstance();
 
-    this.bindSubscribable<CounterState>(
-      {
-        subscribe: (listener) =>
-          counterStateHandler.subscribe(() => listener(counterStateHandler.getSnapshot())),
-        getSnapshot: () => counterStateHandler.getSnapshot(),
-      },
+    this.bindSubscribable<CounterState, CounterState>(
+      counterStateHandler,
       (nextCounterState) => {
         onCounterSync(nextCounterState);
         this.setState({ count: nextCounterState.count }, 'sync-counter');
-      }
+      },
+      (counterState) => counterState
+    );
+  }
+
+  getActions(): { noop: () => void } {
+    return {
+      noop: () => undefined,
+    };
+  }
+}
+
+class CounterSignalBucketBridgeStateHandler extends SignalStateHandler<
+  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
     );
   }
 
@@ -165,7 +200,7 @@ describe('Signal State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveBeenCalledTimes(3);
   });
 
   it('should respect global distinct setup when disabled', () => {
@@ -184,7 +219,7 @@ describe('Signal State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(2);
+    expect(spy).toHaveBeenCalledTimes(3);
   });
 
   it('should respect global custom distinct comparator from setupStatusQuo', () => {
@@ -205,7 +240,7 @@ describe('Signal State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledTimes(2);
   });
 
   it('should prefer per-handler distinct options over global setup', () => {
@@ -228,7 +263,7 @@ describe('Signal State Handler', () => {
 
     unsubscribe();
 
-    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledTimes(2);
   });
 
   it('should notify another signal state handler for each singleton counter update', () => {
@@ -250,4 +285,26 @@ describe('Signal State Handler', () => {
 
     bridgeStateHandler.destroy();
   });
+
+  it('should support selector + equality filtering for bindSubscribable', () => {
+    const counterSingleton = makeStateSingleton(() => new CounterSignalStateHandler(0), {
+      destroyOnNoConsumers: false,
+    });
+    const syncSpy = jest.fn();
+    const bridgeStateHandler = new CounterSignalBucketBridgeStateHandler(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/base-state-handler.ts

@@ -1,13 +1,20 @@
 import { withDevTools } from './dev-tools.js';
+import { createSelectorCache, selectWithCache } from '../utils/selector-cache.js';
 
 import type { StateSubscriptionHandler } from '../types/types.js';
 import type { DevTools, MessagePayload } from './dev-tools.js';
+import type { EqualityFn, Selector } from '../utils/selector-cache.js';
 
 type DevToolsOptions = {
   enabled?: boolean;
   namespace: string;
 };
 
+type Subscribable<T> = {
+  subscribe: (listener: (value: T) => void) => () => void;
+  getSnapshot?: () => T;
+};
+
 const defaultDevToolsOptions = { enabled: false, namespace: 'Store' };
 
 const devToolsFeatures = {
@@ -78,17 +85,53 @@ export abstract class BaseStateHandler<S, A> implements StateSubscriptionHandler
 
   protected abstract getStateValue(): S;
   protected abstract setStateValue(nextState: S): void;
+
   protected bindSubscribable<T>(
-    service: { subscribe: (listener: (value: T) => void) => () => void; getSnapshot?: () => T },
-    onChange: (value: T) => void
+    service: Subscribable<T>,
+    onChange: (value: T) => void,
+    selector?: Selector<T, T>,
+    isEqual?: EqualityFn<T>
+  ): void;
+  protected bindSubscribable<T, Sel>(
+    service: Subscribable<T>,
+    onChange: (value: Sel) => void,
+    selector: Selector<T, Sel>,
+    isEqual?: EqualityFn<Sel>
+  ): void;
+  protected bindSubscribable<T, Sel = T>(
+    service: Subscribable<T>,
+    onChange: (value: Sel) => void,
+    selector?: Selector<T, Sel>,
+    isEqual: EqualityFn<Sel> = Object.is
   ) {
-    const unsubscribe = service.subscribe(onChange);
+    const selectorFn = (selector ?? ((value: T) => value as unknown as Sel)) as Selector<T, Sel>;
+    const selectorCache = createSelectorCache<Sel>();
+    let receivedSyncValue = false;
+
+    const notifySelectedValue = (value: T) => {
+      receivedSyncValue = true;
+      const { value: nextSelection, hasChanged } = selectWithCache(
+        selectorCache,
+        value,
+        selectorFn,
+        isEqual
+      );
+
+      if (!hasChanged) {
+        return;
+      }
+
+      onChange(nextSelection);
+    };
+
+    const unsubscribe = service.subscribe(notifySelectedValue);
     this.subscriptions = [...(this.subscriptions ?? []), { unsubscribe }];
 
-    if (service.getSnapshot) onChange(service.getSnapshot());
+    if (service.getSnapshot && !receivedSyncValue) notifySelectedValue(service.getSnapshot());
   }
 
   abstract subscribe(listener: () => void): () => void;
+  abstract subscribe(listener: (value: S) => void): () => void;
   abstract getActions(): A;
 
   private handleDevToolsEvents = (message: MessagePayload) => {

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

@@ -70,15 +70,11 @@ export abstract class ObservableStateHandler<S, A> extends BaseStateHandler<S, A
     return this.getObservable(key);
   }
 
-  subscribe(listener: () => void) {
-    let initialized = false;
-    const subscription = this.getStateAsObservable().subscribe(() => {
-      if (!initialized) {
-        initialized = true;
-        return;
-      }
-
-      listener();
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: S) => void): () => void;
+  subscribe(listener: (value: S) => void) {
+    const subscription = this.getStateAsObservable().subscribe((nextState) => {
+      listener(nextState);
     });
     return () => subscription.unsubscribe();
   }

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

@@ -18,8 +18,6 @@ type SignalStateHandlerProps<S> = {
   };
 };
 
-type Listener = () => void;
-
 export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
   private readonly state: Signal<S>;
   private readonly distinctOptions: ReturnType<typeof resolveDistinctOptions<S>>;
@@ -36,7 +34,9 @@ export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
     return this.state;
   }
 
-  subscribe(listener: Listener) {
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: S) => void): () => void;
+  subscribe(listener: (value: S) => void) {
     let initialized = false;
     let previousSnapshot = this.state.value;
 
@@ -44,6 +44,7 @@ export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
       if (!initialized) {
         initialized = true;
         previousSnapshot = nextState;
+        listener(nextState);
         return;
       }
 
@@ -53,7 +54,7 @@ export abstract class SignalStateHandler<S, A> extends BaseStateHandler<S, A> {
       }
 
       previousSnapshot = nextState;
-      listener();
+      listener(nextState);
     });
   }
 

package/src/types/types.ts

@@ -1,5 +1,6 @@
 export interface StateSubscriptionHandler<V, A> {
-  subscribe: (listener: () => void) => () => void;
+  subscribe(listener: () => void): () => void;
+  subscribe(listener: (value: V) => void): () => void;
   getSnapshot: () => V;
   destroy: () => void;
   getInitialState: () => V;

package/src/utils/selector-cache.ts

@@ -0,0 +1,43 @@
+export type Selector<Value, Selected> = (value: Value) => Selected;
+export type EqualityFn<Selected> = (current: Selected, next: Selected) => boolean;
+
+type SelectorCache<Selected> = {
+  hasValue: boolean;
+  value: Selected | undefined;
+};
+
+type SelectionResult<Selected> = {
+  value: Selected;
+  hasChanged: boolean;
+};
+
+export function createSelectorCache<Selected>(): SelectorCache<Selected> {
+  return {
+    hasValue: false,
+    value: undefined,
+  };
+}
+
+export function selectWithCache<Value, Selected>(
+  selectorCache: SelectorCache<Selected>,
+  value: Value,
+  selector: Selector<Value, Selected>,
+  isEqual: EqualityFn<Selected> = Object.is
+): SelectionResult<Selected> {
+  const nextSelection = selector(value);
+
+  if (selectorCache.hasValue && isEqual(selectorCache.value as Selected, nextSelection)) {
+    return {
+      value: selectorCache.value as Selected,
+      hasChanged: false,
+    };
+  }
+
+  selectorCache.hasValue = true;
+  selectorCache.value = nextSelection;
+
+  return {
+    value: nextSelection,
+    hasChanged: true,
+  };
+}