Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added reasonining and when to use to proxyMap and proxySet #978

Merged
merged 1 commit into from
Oct 19, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/api/utils/proxyMap.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,14 @@ description: ''

# `proxyMap`

## Reasoning

Native `Maps` store their data in internal slots which are not observable. This means that `valtio` cannot track changes to the data inside of a native `Map`. `proxyMap` is a utility that allows you to create a proxy that mimics the behavior of a `Map` while still allowing valtio to track changes to the data.

## When to use `proxyMap`

`proxyMap` is useful when you need the flexibility of a `Map` but still want to track changes to the data. It can be useful if you don't know the structure of the data you'll be working with and this data may have non-primitive values as keys (e.g. objects, arrays, etc.). In this case, you can use `proxyMap` to create a proxy that mimics the behavior of a `Map` while still allowing valtio to track changes to the data. If your data can be represented as a simple object, you should use `proxy` with a simple object instead. It is more performant and easier to use.

## Use a js Map with Valtio

This utility creates a proxy which mimics the native Map behavior. The API is the same as the Map API.
Expand Down
19 changes: 19 additions & 0 deletions docs/api/utils/proxySet.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ description: ''

# `proxySet`

## Reasoning

Native `Sets` store their data in internal slots which are not observable. This means that `valtio` cannot track changes to the data inside of a native `Set`. `proxySet` is a utility that allows you to create a proxy that mimics the behavior of a `Set` while still allowing valtio to track changes to the data.

## When to use `proxySet`

`proxySet` is useful when you need the functionality of a `Set` but still want to track changes to the data. `proxySet` can be useful if you're wanting to store unique values or if you want to perform mathematical `Set` operations on the data, such as union, intersection, or difference. `proxySet` supports all of the new methods introduced to `Set`:

- `intersection`
- `isDisjointFrom`
- `isSubsetOf`
- `isSupersetOf`
- `symmetricDifference`
- `union`

You can see a full list of the methods supported by `proxySet` in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set).

If your data can be represented as a simple array or object, and you have no need for the additional functionality provided by `proxySet`, you should use `proxy` with a simple array or object instead. It is more performant and easier to use.

## Use a js `Set` with Valtio

This utility creates a proxy which mimics the native `Set` behavior. The API is the same as the native `Set` API.
Expand Down