From a0ea8c33030c4154ed85118ab89d6e7ef9bd2d7c Mon Sep 17 00:00:00 2001 From: Michael Sweeney Date: Sat, 19 Oct 2024 04:04:37 -0700 Subject: [PATCH] added reasonining and when to use to proxyMap and proxySet --- docs/api/utils/proxyMap.mdx | 8 ++++++++ docs/api/utils/proxySet.mdx | 19 +++++++++++++++++++ 2 files changed, 27 insertions(+) diff --git a/docs/api/utils/proxyMap.mdx b/docs/api/utils/proxyMap.mdx index e6d7f8b4..4a346433 100644 --- a/docs/api/utils/proxyMap.mdx +++ b/docs/api/utils/proxyMap.mdx @@ -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. diff --git a/docs/api/utils/proxySet.mdx b/docs/api/utils/proxySet.mdx index 008f1817..0a98f643 100644 --- a/docs/api/utils/proxySet.mdx +++ b/docs/api/utils/proxySet.mdx @@ -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.