feat: allow specifying comparator / equality function (#244)

* Add test case for deep nested comparison

* Add equality function

* Add option for custom equal function everywhere

* ci: apply automated fixes and generate docs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: aburto22

docs/framework/react/reference/functions/shallow.md

@@ -11,7 +11,7 @@ title: shallow
 function shallow<T>(objA, objB): boolean
 ```
 
-Defined in: [index.ts:34](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L34)
+Defined in: [index.ts:42](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L42)
 
 ## Type Parameters
 

docs/framework/react/reference/functions/usestore.md

@@ -10,10 +10,13 @@ title: useStore
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): TSelected
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+   options?): TSelected
 ```
 
-Defined in: [index.ts:11](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L11)
+Defined in: [index.ts:15](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L15)
 
 ### Type Parameters
 
@@ -31,17 +34,24 @@ Defined in: [index.ts:11](https://github.com/TanStack/store/blob/main/packages/r
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `TSelected`
 
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): TSelected
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+   options?): TSelected
 ```
 
-Defined in: [index.ts:15](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L15)
+Defined in: [index.ts:20](https://github.com/TanStack/store/blob/main/packages/react-store/src/index.ts#L20)
 
 ### Type Parameters
 
@@ -59,6 +69,10 @@ Defined in: [index.ts:15](https://github.com/TanStack/store/blob/main/packages/r
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `TSelected`

docs/framework/solid/reference/functions/shallow.md

@@ -11,7 +11,7 @@ title: shallow
 function shallow<T>(objA, objB): boolean
 ```
 
-Defined in: [index.tsx:41](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L41)
+Defined in: [index.tsx:49](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L49)
 
 ## Type Parameters
 

docs/framework/solid/reference/functions/usestore.md

@@ -10,10 +10,13 @@ title: useStore
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): Accessor<TSelected>
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+options?): Accessor<TSelected>
 ```
 
-Defined in: [index.tsx:12](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L12)
+Defined in: [index.tsx:16](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L16)
 
 ### Type Parameters
 
@@ -31,17 +34,24 @@ Defined in: [index.tsx:12](https://github.com/TanStack/store/blob/main/packages/
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `Accessor`\<`TSelected`\>
 
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): Accessor<TSelected>
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+options?): Accessor<TSelected>
 ```
 
-Defined in: [index.tsx:16](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L16)
+Defined in: [index.tsx:21](https://github.com/TanStack/store/blob/main/packages/solid-store/src/index.tsx#L21)
 
 ### Type Parameters
 
@@ -59,6 +69,10 @@ Defined in: [index.tsx:16](https://github.com/TanStack/store/blob/main/packages/
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `Accessor`\<`TSelected`\>

docs/framework/svelte/reference/functions/shallow.md

@@ -11,7 +11,7 @@ title: shallow
 function shallow<T>(objA, objB): boolean
 ```
 
-Defined in: [index.svelte.ts:43](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L43)
+Defined in: [index.svelte.ts:51](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L51)
 
 ## Type Parameters
 

docs/framework/svelte/reference/functions/usestore.md

@@ -10,10 +10,13 @@ title: useStore
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): object
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+   options?): object
 ```
 
-Defined in: [index.svelte.ts:10](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L10)
+Defined in: [index.svelte.ts:14](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L14)
 
 ### Type Parameters
 
@@ -31,6 +34,10 @@ Defined in: [index.svelte.ts:10](https://github.com/TanStack/store/blob/main/pac
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `object`
@@ -44,10 +51,13 @@ readonly current: TSelected;
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): object
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+   options?): object
 ```
 
-Defined in: [index.svelte.ts:14](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L14)
+Defined in: [index.svelte.ts:19](https://github.com/TanStack/store/blob/main/packages/svelte-store/src/index.svelte.ts#L19)
 
 ### Type Parameters
 
@@ -65,6 +75,10 @@ Defined in: [index.svelte.ts:14](https://github.com/TanStack/store/blob/main/pac
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `object`

docs/framework/vue/reference/functions/shallow.md

@@ -11,7 +11,7 @@ title: shallow
 function shallow<T>(objA, objB): boolean
 ```
 
-Defined in: [index.ts:47](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L47)
+Defined in: [index.ts:55](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L55)
 
 ## Type Parameters
 

docs/framework/vue/reference/functions/usestore.md

@@ -10,10 +10,13 @@ title: useStore
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): Readonly<Ref<TSelected, TSelected>>
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+options?): Readonly<Ref<TSelected, TSelected>>
 ```
 
-Defined in: [index.ts:12](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L12)
+Defined in: [index.ts:16](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L16)
 
 ### Type Parameters
 
@@ -31,17 +34,24 @@ Defined in: [index.ts:12](https://github.com/TanStack/store/blob/main/packages/v
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `Readonly`\<`Ref`\<`TSelected`, `TSelected`\>\>
 
 ## Call Signature
 
 ```ts
-function useStore<TState, TSelected>(store, selector?): Readonly<Ref<TSelected, TSelected>>
+function useStore<TState, TSelected>(
+   store, 
+   selector?, 
+options?): Readonly<Ref<TSelected, TSelected>>
 ```
 
-Defined in: [index.ts:16](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L16)
+Defined in: [index.ts:21](https://github.com/TanStack/store/blob/main/packages/vue-store/src/index.ts#L21)
 
 ### Type Parameters
 
@@ -59,6 +69,10 @@ Defined in: [index.ts:16](https://github.com/TanStack/store/blob/main/packages/v
 
 (`state`) => `TSelected`
 
+#### options?
+
+`UseStoreOptions`\<`TSelected`\>
+
 ### Returns
 
 `Readonly`\<`Ref`\<`TSelected`, `TSelected`\>\>

packages/react-store/src/index.ts

@@ -7,25 +7,33 @@ export * from '@tanstack/store'
  * @private
  */
 export type NoInfer<T> = [T][T extends any ? 0 : never]
+type EqualityFn<T> = (objA: T, objB: T) => boolean
+interface UseStoreOptions<T> {
+  equal?: EqualityFn<T>
+}
 
 export function useStore<TState, TSelected = NoInfer<TState>>(
   store: Store<TState, any>,
   selector?: (state: NoInfer<TState>) => TSelected,
+  options?: UseStoreOptions<TSelected>,
 ): TSelected
 export function useStore<TState, TSelected = NoInfer<TState>>(
   store: Derived<TState, any>,
   selector?: (state: NoInfer<TState>) => TSelected,
+  options?: UseStoreOptions<TSelected>,
 ): TSelected
 export function useStore<TState, TSelected = NoInfer<TState>>(
   store: Store<TState, any> | Derived<TState, any>,
   selector: (state: NoInfer<TState>) => TSelected = (d) => d as any,
+  options: UseStoreOptions<TSelected> = {},
 ): TSelected {
+  const equal = options.equal ?? shallow
   const slice = useSyncExternalStoreWithSelector(
     store.subscribe,
     () => store.state,
     () => store.state,
     selector,
-    shallow,
+    equal,
   )
 
   return slice

packages/react-store/tests/index.test.tsx

@@ -78,6 +78,78 @@ describe('useStore', () => {
     expect(getByText('Number rendered: 2')).toBeInTheDocument()
   })
 
+  it('allow specifying custom equality function', async () => {
+    const store = new Store({
+      array: [
+        { select: 0, ignore: 1 },
+        { select: 0, ignore: 1 },
+      ],
+    })
+
+    function deepEqual<T>(objA: T, objB: T) {
+      return JSON.stringify(objA) === JSON.stringify(objB)
+    }
+
+    function Comp() {
+      const storeVal = useStore(
+        store,
+        (state) => state.array.map(({ ignore, ...rest }) => rest),
+        { equal: deepEqual },
+      )
+      const [fn] = useState(vi.fn)
+      fn()
+
+      const value = storeVal
+        .map((item) => item.select)
+        .reduce((total, num) => total + num, 0)
+
+      return (
+        <div>
+          <p>Number rendered: {fn.mock.calls.length}</p>
+          <p>Store: {value}</p>
+          <button
+            type="button"
+            onClick={() =>
+              store.setState((v) => ({
+                array: v.array.map((item) => ({
+                  ...item,
+                  select: item.select + 5,
+                })),
+              }))
+            }
+          >
+            Update select
+          </button>
+          <button
+            type="button"
+            onClick={() =>
+              store.setState((v) => ({
+                array: v.array.map((item) => ({
+                  ...item,
+                  ignore: item.ignore + 2,
+                })),
+              }))
+            }
+          >
+            Update ignored
+          </button>
+        </div>
+      )
+    }
+
+    const { getByText } = render(<Comp />)
+    expect(getByText('Store: 0')).toBeInTheDocument()
+    expect(getByText('Number rendered: 1')).toBeInTheDocument()
+
+    await user.click(getByText('Update select'))
+
+    await waitFor(() => expect(getByText('Store: 10')).toBeInTheDocument())
+    expect(getByText('Number rendered: 2')).toBeInTheDocument()
+
+    await user.click(getByText('Update ignored'))
+    expect(getByText('Number rendered: 2')).toBeInTheDocument()
+  })
+
   it('works with mounted derived stores', async () => {
     const store = new Store(0)