fix(readme): description with createWithEqualityFn #1985

dai-shi · 2023-08-09T03:41:25Z

Related Issues or Discussions

#1937 (reply in thread)

Summary

Clarify to use createWithEqualityFn for shallow.

Check List

yarn run prettier for formatting code and docs

vercel · 2023-08-09T03:41:28Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
zustand-demo	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Aug 12, 2023 2:28am

codesandbox-ci · 2023-08-09T03:41:50Z

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit a757a25:

Sandbox	Source
React	Configuration
React Typescript	Configuration
React Browserify	Configuration
React Snowpack	Configuration
React Parcel	Configuration
Next.js	Configuration
@pavlobu/zustand demo	Configuration

github-actions · 2023-08-09T03:42:52Z

Size Change: 0 B

Total Size: 43.5 kB

ℹ️ View Unchanged

Filename	Size
`dist/context.js`	782 B
`dist/esm/context.js`	590 B
`dist/esm/index.js`	706 B
`dist/esm/middleware.js`	3.87 kB
`dist/esm/middleware/immer.js`	210 B
`dist/esm/shallow.js`	509 B
`dist/esm/traditional.js`	392 B
`dist/esm/vanilla.js`	629 B
`dist/index.js`	868 B
`dist/middleware.js`	4.43 kB
`dist/middleware/immer.js`	328 B
`dist/shallow.js`	1.11 kB
`dist/system/context.development.js`	697 B
`dist/system/context.production.js`	386 B
`dist/system/index.development.js`	873 B
`dist/system/index.production.js`	402 B
`dist/system/middleware.development.js`	4 kB
`dist/system/middleware.production.js`	2.62 kB
`dist/system/middleware/immer.development.js`	292 B
`dist/system/middleware/immer.production.js`	187 B
`dist/system/shallow.development.js`	558 B
`dist/system/shallow.production.js`	344 B
`dist/system/traditional.development.js`	505 B
`dist/system/traditional.production.js`	342 B
`dist/system/vanilla.development.js`	672 B
`dist/system/vanilla.production.js`	310 B
`dist/traditional.js`	433 B
`dist/umd/context.development.js`	887 B
`dist/umd/context.production.js`	556 B
`dist/umd/index.development.js`	999 B
`dist/umd/index.production.js`	543 B
`dist/umd/middleware.development.js`	4.58 kB
`dist/umd/middleware.production.js`	2.97 kB
`dist/umd/middleware/immer.development.js`	482 B
`dist/umd/middleware/immer.production.js`	342 B
`dist/umd/shallow.development.js`	1.23 kB
`dist/umd/shallow.production.js`	883 B
`dist/umd/traditional.development.js`	613 B
`dist/umd/traditional.production.js`	447 B
`dist/umd/vanilla.development.js`	800 B
`dist/umd/vanilla.production.js`	410 B
`dist/vanilla.js`	683 B

_{compressed-size-action}

sewera · 2023-08-09T07:07:32Z

readme.md

@@ -86,9 +86,22 @@ const honey = useBearStore((state) => state.honey)

 If you want to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can tell zustand that you want the object to be diffed shallowly by passing the `shallow` equality function.

+To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.


I feel it's a bit confusing — "to use a custom equality function" and then "for the default equality function."

Is the default eq fn a default for that store, but you can still override it later? If so, I suggest:

Suggested change

To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.

To use a custom equality function that will become a new default for the store, you need `createWithEqualityFn` from `zustand/traditional`.

Pass an equality function as a second argument.

Thanks for the suggestion. Let me clarify and maybe you have some other suggestions.

create (in v5) doesn't allow changing equality function. (It's always Object.is equivalent.)

To use custom equality function, createWithEqualityFn is necessary.

The signature is const useMyStore = createEqualityFn(..., defaultEqualityFn).

useMyStore(selector, equalityFn) can override the default equality function.

If you specify Object.is for the second argument of createEqualityFn, it behave the same as create < v4.4.0.

Alright, so my proposal:

Suggested change

To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.

To use a custom equality function that will become a new default for the store, you need `createWithEqualityFn` from `zustand/traditional`.

Pass a desired equality function as a second argument, like so:

What I was concerning is the backward compatibility with previous version. But, I think it's not super important.

for the store

It's not for the store (which is still Objet.is), but it's for the hook.

"To use a custom equality function, you need createWithEqualityFn instead of create. Usually, specify Object.is at the second argument for the default equality function, but it's configurable." How about that?

"To use a custom equality function, you need createWithEqualityFn instead of create. Usually you want to specify Object.is as the second argument for the default equality function, but it's configurable."

Thanks. I'll update it later.

sewera · 2023-08-09T07:10:55Z

readme.md

+    increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
+    removeAllBears: () => set({ bears: 0 }),
+  }),
+  Object.is // Specify the default equality function, which can be shallow


If the eq fn is shallow, what is the effect of using 'zustand/shallow'? Isn't the eq fn always shallow then, regardless of it?

If you do this:

import { createWithEqualityFn } from 'zustand/traditional' import { shallow } from 'zustand/shallow' const useMyStore = createWithEqualityFn(..., shallow)

You don't need to specify shallow for useMyStore:

useMyStore(...) // that 👆 is the same as this 👇 useMyStore(..., shallow)

Suggested change

Object.is // Specify the default equality function, which can be shallow

customEqualityFunction // This will become the default equality function, unless you pass another one to `useBearStore` hook.

And then I'd add a customEqualityFunction.

customEqualityFunction is not defined anywhere, so I think it's confusing.

I thought about defining it, but you said that readme should be minimal, and I agree, so I don't push that hard on this.

sewera

I'd explicitly write some example of an actually different equality function than the Object.is to highlight the use case.

One use case I can think about that better highlights what a real-world scenario could be would be something like:

const useNotificationStore = createWithEqualityFn(set => ({
    notifications: []
    addNotification: notification => set(state => ({ notifications: [...state.notifications, notification] }))
  }),
  hashEquality
)

function hashEquality(a, b) {
  return JSON.stringify(a.notifications.map(it => it.hash)) === JSON.stringify(b.notifications.map(it => it.hash))
}

provided that notification hash is computed in backend.

sewera · 2023-08-09T12:08:06Z

readme.md

@@ -86,9 +86,22 @@ const honey = useBearStore((state) => state.honey)

 If you want to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can tell zustand that you want the object to be diffed shallowly by passing the `shallow` equality function.

+To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.


Alright, so my proposal:

Suggested change

To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.

To use a custom equality function that will become a new default for the store, you need `createWithEqualityFn` from `zustand/traditional`.

Pass a desired equality function as a second argument, like so:

sewera · 2023-08-09T12:10:43Z

readme.md

+    increasePopulation: () => set((state) => ({ bears: state.bears + 1 })),
+    removeAllBears: () => set({ bears: 0 }),
+  }),
+  Object.is // Specify the default equality function, which can be shallow


Suggested change

Object.is // Specify the default equality function, which can be shallow

customEqualityFunction // This will become the default equality function, unless you pass another one to `useBearStore` hook.

And then I'd add a customEqualityFunction.

sewera · 2023-08-09T12:13:34Z

readme.md

 ```jsx
+import { createWithEqualityFn } from 'zustand/traditional'
 import { shallow } from 'zustand/shallow'



Suggested change

const customEqualityFunction = (a, b) => a.bears === b.bears

dai-shi · 2023-08-09T13:00:09Z

I'd explicitly write some example

That would be good, but our strong desire is to keep readme.md as minimal as possible.
So, what I'd like to do is to show something very essential in readme.md and link to docs for details.
See: https://github.com/pmndrs/zustand#typescript-usage

sewera · 2023-08-09T13:16:48Z

You're right. I still suggest this rephrasal: #1985 (comment)

fix(readme): description with createWithEqualityFn

f79020b

sewera suggested changes Aug 9, 2023

View reviewed changes

fix wording

a757a25

vercel bot deployed to Preview August 12, 2023 02:28 View deployment

dai-shi requested a review from sewera August 12, 2023 02:28

sewera approved these changes Aug 12, 2023

View reviewed changes

dai-shi merged commit 49d43b7 into main Aug 12, 2023

dai-shi deleted the fix/readme branch August 12, 2023 10:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(readme): description with createWithEqualityFn #1985

fix(readme): description with createWithEqualityFn #1985

dai-shi commented Aug 9, 2023

vercel bot commented Aug 9, 2023 •

edited

Loading

codesandbox-ci bot commented Aug 9, 2023 •

edited

Loading

github-actions bot commented Aug 9, 2023 •

edited

Loading

sewera Aug 9, 2023

dai-shi Aug 9, 2023

sewera Aug 9, 2023

dai-shi Aug 9, 2023

dai-shi Aug 9, 2023

dai-shi Aug 9, 2023

sewera Aug 9, 2023

dai-shi Aug 10, 2023

sewera Aug 9, 2023

dai-shi Aug 9, 2023

sewera Aug 9, 2023

dai-shi Aug 9, 2023

sewera Aug 9, 2023

sewera left a comment

sewera Aug 9, 2023

sewera Aug 9, 2023

sewera Aug 9, 2023

dai-shi commented Aug 9, 2023

sewera commented Aug 9, 2023

		@@ -86,9 +86,22 @@ const honey = useBearStore((state) => state.honey)

		If you want to construct a single object with multiple state-picks inside, similar to redux's mapStateToProps, you can tell zustand that you want the object to be diffed shallowly by passing the `shallow` equality function.

		To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.

	To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.
	To use a custom equality function that will become a new default for the store, you need `createWithEqualityFn` from `zustand/traditional`.
	Pass an equality function as a second argument.

	To use a custom equality function, you need `createWithEqualityFn` from `zustand/traditional`. It takes the second argument for the default equality function.
	To use a custom equality function that will become a new default for the store, you need `createWithEqualityFn` from `zustand/traditional`.
	Pass a desired equality function as a second argument, like so:

	Object.is // Specify the default equality function, which can be shallow
	customEqualityFunction // This will become the default equality function, unless you pass another one to `useBearStore` hook.



	const customEqualityFunction = (a, b) => a.bears === b.bears

fix(readme): description with createWithEqualityFn #1985

fix(readme): description with createWithEqualityFn #1985

Conversation

dai-shi commented Aug 9, 2023

Related Issues or Discussions

Summary

Check List

vercel bot commented Aug 9, 2023 • edited Loading

codesandbox-ci bot commented Aug 9, 2023 • edited Loading

github-actions bot commented Aug 9, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sewera left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dai-shi commented Aug 9, 2023

sewera commented Aug 9, 2023

vercel bot commented Aug 9, 2023 •

edited

Loading

codesandbox-ci bot commented Aug 9, 2023 •

edited

Loading

github-actions bot commented Aug 9, 2023 •

edited

Loading