[@xstate/store-angular @xstate/store-svelte @xstate/store-vue] Compare option consistency (#5452)

* Replace 'options' with 'compare' function + changeset

* Fix import

Author: davidkpiano

.changeset/stale-buses-stand.md

@@ -0,0 +1,7 @@
+---
+'@xstate/store-angular': minor
+'@xstate/store-svelte': minor
+'@xstate/store-vue': minor
+---
+
+Ensured that `compare` argument is a direct comparison function.

packages/xstate-store-angular/README.md

@@ -36,7 +36,7 @@ export class CounterComponent {
 
 ## API
 
-### `injectStore(store, selector?, options?)`
+### `injectStore(store, selector?, compare?)`
 
 An Angular function that creates a signal subscribed to a store, selecting a value via an optional selector function.
 
@@ -67,7 +67,7 @@ export class CounterComponent {
 
 - `store` - Store created with `createStore()`
 - `selector?` - Function to select a value from snapshot
-- `options?` - Signal creation options with optional `equal` function and `injector`
+- `compare?` - Equality function (default: `===`)
 
 **Returns:** Readonly Angular signal of the selected value
 

packages/xstate-store-angular/src/index.test.ts

@@ -134,6 +134,66 @@ describe('@xstate/store-angular', () => {
       expect(fixture.nativeElement.textContent).toContain('10');
       expect(effectCount).toBe(2); // No re-render for ignored field
     });
+
+    it('should use custom comparison function', () => {
+      const store = createStore({
+        context: { items: [1, 2] },
+        on: {
+          same: (ctx) => ({ ...ctx, items: [1, 2] }),
+          different: (ctx) => ({ ...ctx, items: [3, 4] })
+        }
+      });
+
+      let effectCount = 0;
+
+      @Component({
+        template: `
+          <p id="items">{{ items() }}</p>
+          <button id="same" (click)="sendSame()">Same</button>
+          <button id="different" (click)="sendDifferent()">Different</button>
+        `,
+        standalone: true
+      })
+      class TestComponent {
+        items = injectStore(
+          store,
+          (state) => state.context.items,
+          (a, b) => JSON.stringify(a) === JSON.stringify(b)
+        );
+
+        constructor() {
+          effect(() => {
+            console.log(this.items());
+            effectCount++;
+          });
+        }
+
+        sendSame() {
+          store.send({ type: 'same' });
+        }
+
+        sendDifferent() {
+          store.send({ type: 'different' });
+        }
+      }
+
+      const fixture = TestBed.createComponent(TestComponent);
+      fixture.detectChanges();
+
+      const debugElement = fixture.debugElement;
+
+      expect(effectCount).toBe(1); // Initial
+
+      debugElement.query(By.css('#same')).triggerEventHandler('click', null);
+      fixture.detectChanges();
+      expect(effectCount).toBe(1); // Same content, should not trigger
+
+      debugElement
+        .query(By.css('#different'))
+        .triggerEventHandler('click', null);
+      fixture.detectChanges();
+      expect(effectCount).toBe(2); // Different content
+    });
   });
 
   describe('re-exports', () => {

packages/xstate-store-angular/src/index.ts

@@ -8,8 +8,12 @@ import {
   linkedSignal,
   runInInjectionContext
 } from '@angular/core';
-import type { CreateSignalOptions, Signal } from '@angular/core';
-import { shallowEqual, type Readable } from '@xstate/store';
+import type { Signal } from '@angular/core';
+import { type Readable } from '@xstate/store';
+
+function defaultCompare<T>(a: T, b: T) {
+  return a === b;
+}
 
 /**
  * An Angular function that creates a signal subscribed to a store, selecting a
@@ -34,32 +38,28 @@ import { shallowEqual, type Readable } from '@xstate/store';
  * @param store The store, created from `createStore(…)`
  * @param selector A function which takes in the snapshot and returns a selected
  *   value
- * @param options Optional signal creation options with compare function and
- *   injector
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
  * @returns A readonly Signal of the selected value
  */
 export function injectStore<TStore extends Readable<any>, TSelected>(
   store: TStore,
   selector?: (state: TStore extends Readable<infer T> ? T : never) => TSelected,
-  options?: CreateSignalOptions<TSelected> & { injector?: Injector }
+  compare?: (a: TSelected, b: TSelected) => boolean
 ): Signal<TSelected>;
 export function injectStore<TStore extends Readable<any>, TSelected>(
   store: TStore,
   selector: (
     state: TStore extends Readable<infer T> ? T : never
   ) => TSelected = (d) => d as TSelected,
-  options: CreateSignalOptions<TSelected> & { injector?: Injector } = {
-    equal: shallowEqual
-  }
+  compare: (a: TSelected, b: TSelected) => boolean = defaultCompare
 ): Signal<TSelected> {
-  if (!options.injector) {
-    assertInInjectionContext(injectStore);
-    options.injector = inject(Injector);
-  }
+  assertInInjectionContext(injectStore);
+  const injector = inject(Injector);
 
-  return runInInjectionContext(options.injector, () => {
+  return runInInjectionContext(injector, () => {
     const destroyRef = inject(DestroyRef);
-    const slice = linkedSignal(() => selector(store.get()), options);
+    const slice = linkedSignal(() => selector(store.get()), { equal: compare });
 
     const { unsubscribe } = store.subscribe((s) => {
       slice.set(selector(s));

packages/xstate-store-svelte/README.md

@@ -32,7 +32,7 @@ const count = useSelector(store, (s) => s.context.count);
 
 ## API
 
-### `useSelector(store, selector?, options?)`
+### `useSelector(store, selector?, compare?)`
 
 Creates a Svelte readable store that subscribes to an XState store and returns a selected value.
 
@@ -60,7 +60,7 @@ const snapshot = useSelector(store);
 
 - `store` - Store created with `createStore()`
 - `selector?` - Function to select a value from snapshot
-- `options?` - Object with optional `compare` equality function
+- `compare?` - Equality function (default: `===`)
 
 **Returns:** Svelte readable store
 

packages/xstate-store-svelte/src/index.test.ts

@@ -55,9 +55,11 @@ describe('@xstate/store-svelte', () => {
       });
 
       let updateCount = 0;
-      const items$ = useSelector(store, (s) => s.context.items, {
-        compare: (a, b) => JSON.stringify(a) === JSON.stringify(b)
-      });
+      const items$ = useSelector(
+        store,
+        (s) => s.context.items,
+        (a, b) => JSON.stringify(a) === JSON.stringify(b)
+      );
 
       const unsubscribe = items$.subscribe(() => {
         updateCount++;

packages/xstate-store-svelte/src/index.ts

@@ -1,12 +1,10 @@
 export * from '@xstate/store';
 
-import { shallowEqual, type Readable as XStateReadable } from '@xstate/store';
+import { type Readable as XStateReadable } from '@xstate/store';
 import type { Readable } from 'svelte/store';
 
-type EqualityFn<T> = (objA: T, objB: T) => boolean;
-
-interface UseSelectorOptions<T> {
-  compare?: EqualityFn<T>;
+function defaultCompare<T>(a: T, b: T) {
+  return a === b;
 }
 
 /**
@@ -29,18 +27,17 @@ interface UseSelectorOptions<T> {
  * @param store The store, created from `createStore(…)`
  * @param selector A function which takes in the snapshot and returns a selected
  *   value
- * @param options Optional configuration with compare function
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
  * @returns A Svelte readable store
  */
 export function useSelector<TStore extends XStateReadable<any>, TSelected>(
   store: TStore,
   selector: (
     state: TStore extends XStateReadable<infer T> ? T : never
   ) => TSelected = (d) => d as any,
-  options: UseSelectorOptions<TSelected> = {}
+  compare: (a: TSelected, b: TSelected) => boolean = defaultCompare
 ): Readable<TSelected> {
-  const compare = options.compare ?? shallowEqual;
-
   return {
     subscribe(run) {
       let currentValue = selector(store.get());

packages/xstate-store-vue/README.md

@@ -32,7 +32,7 @@ const count = useSelector(store, (s) => s.context.count);
 
 ## API
 
-### `useSelector(store, selector?, options?)`
+### `useSelector(store, selector?, compare?)`
 
 A composable that subscribes to a store and returns a selected value as a readonly ref.
 
@@ -62,7 +62,7 @@ const snapshot = useSelector(store);
 
 - `store` - Store created with `createStore()`
 - `selector?` - Function to select a value from snapshot
-- `options?` - Object with optional `compare` equality function
+- `compare?` - Equality function (default: `===`)
 
 **Returns:** Readonly ref of the selected value
 

packages/xstate-store-vue/src/index.test.ts

@@ -1,6 +1,6 @@
 import { fireEvent, render } from '@testing-library/vue';
 import TestCounter from './TestCounter.vue';
-import { createStore, createAtom } from './index';
+import { createStore, createAtom, useSelector } from './index';
 
 describe('@xstate/store-vue', () => {
   describe('useSelector', () => {
@@ -15,6 +15,43 @@ describe('@xstate/store-vue', () => {
       await fireEvent.click(incrementEl);
       expect(countEl.textContent).toBe('1');
     });
+
+    it('should use custom comparison function', async () => {
+      const store = createStore({
+        context: { items: [1, 2] },
+        on: {
+          same: (ctx) => ({ ...ctx, items: [1, 2] }),
+          different: (ctx) => ({ ...ctx, items: [3, 4] })
+        }
+      });
+
+      let updateCount = 0;
+      const items = useSelector(
+        store,
+        (s) => s.context.items,
+        (a, b) => JSON.stringify(a) === JSON.stringify(b)
+      );
+
+      // Vue refs need to be watched to track updates
+      const { watch } = await import('vue');
+      watch(
+        items,
+        () => {
+          updateCount++;
+        },
+        { immediate: true }
+      );
+
+      expect(updateCount).toBe(1); // Initial
+
+      store.send({ type: 'same' }); // Same content, should not trigger
+      await new Promise((r) => setTimeout(r, 0));
+      expect(updateCount).toBe(1);
+
+      store.send({ type: 'different' }); // Different content
+      await new Promise((r) => setTimeout(r, 0));
+      expect(updateCount).toBe(2);
+    });
   });
 
   describe('re-exports', () => {

packages/xstate-store-vue/src/index.ts

@@ -2,12 +2,10 @@ export * from '@xstate/store';
 
 import { readonly, ref, toRaw, watch } from 'vue-demi';
 import type { Ref } from 'vue-demi';
-import { shallowEqual, type Readable } from '@xstate/store';
+import { type Readable } from '@xstate/store';
 
-type EqualityFn<T> = (objA: T, objB: T) => boolean;
-
-interface UseSelectorOptions<T> {
-  compare?: EqualityFn<T>;
+function defaultCompare<T>(a: T, b: T) {
+  return a === b;
 }
 
 /**
@@ -32,18 +30,18 @@ interface UseSelectorOptions<T> {
  * @param store The store, created from `createStore(…)`
  * @param selector A function which takes in the snapshot and returns a selected
  *   value
- * @param options Optional configuration with compare function
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
  * @returns A readonly ref of the selected value
  */
 export function useSelector<TStore extends Readable<any>, TSelected>(
   store: TStore,
   selector: (
     state: TStore extends Readable<infer T> ? T : never
   ) => TSelected = (d) => d as any,
-  options: UseSelectorOptions<TSelected> = {}
+  compare: (a: TSelected, b: TSelected) => boolean = defaultCompare
 ): Readonly<Ref<TSelected>> {
   const slice = ref(selector(store.get())) as Ref<TSelected>;
-  const compare = options.compare ?? shallowEqual;
 
   watch(
     () => store,