Skip to content

Commit

Permalink
added reasonining and when to use to proxyMap and proxySet (#978)
Browse files Browse the repository at this point in the history
  • Loading branch information
overthemike authored Oct 19, 2024
1 parent 552992c commit cd361f7
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 0 deletions.
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

0 comments on commit cd361f7

Please sign in to comment.