|
| 1 | +--- |
| 2 | +slug: "/recipe/proxy-instances" |
| 3 | +title: "Proxy Item Instances" |
| 4 | +category: recipe |
| 5 | +--- |
| 6 | + |
| 7 | +Proxy Item Instances are an advanced concept, and is only required if you handle a large number of items |
| 8 | +that is loaded in at the same time. Usually this happens in situations where also [virtualization](/recipe/virtualization) |
| 9 | +is employed. It is suggested to only use this feature if you already notice a performance impact of memory |
| 10 | +usage with the default implementation. |
| 11 | + |
| 12 | +Whenever Headless Tree reacts to changes in the tree structure, e.g. items are expanded or collapsed, or the tree |
| 13 | +structure is mutated (or more specifically, whenever `tree.rebuildTree()` is called), an item instance object |
| 14 | +is created for every item that is part of the tree. This object will contain a reference to every tree item function of every |
| 15 | +feature that is included in the tree. Both the instantiation of the item and keeping it in memory is generally |
| 16 | +a trivial overhead, but with many hundreds or thousands or millions of items, this can still cause a noticable |
| 17 | +memory usage. |
| 18 | + |
| 19 | +The instantiation of tree items is a configurable method, that can be defined with the `instanceBuilder` option. |
| 20 | +This defaults to the `buildStaticInstance` method exposed by Headless Tree, which creates a new static object |
| 21 | +with all the tree item functions resolved inside. |
| 22 | + |
| 23 | +An alternative is the `buildProxiedInstance` method, which creates a proxy object that will only resolve individual |
| 24 | +tree item functions when they are actually called. This reduces memory, since now every item is only a very thin |
| 25 | +proxy object, and all feature-related functions are only maintained in memory once instead of n times. |
| 26 | + |
| 27 | +```ts |
| 28 | +import { |
| 29 | + buildProxiedInstance, |
| 30 | + buildStaticInstance, |
| 31 | +} from "@headless-tree/core"; |
| 32 | +``` |
| 33 | + |
| 34 | +```ts |
| 35 | +const tree = useTree({ |
| 36 | + // ...remaining tree options |
| 37 | + instanceBuilder: buildProxiedInstance, |
| 38 | +}); |
| 39 | +``` |
| 40 | + |
| 41 | +This will already do everything needed to use proxy instances instead of the default static instances. The most |
| 42 | +notable difference is, that now function references in item instances are not stable anymore: |
| 43 | + |
| 44 | +```ts |
| 45 | +const item = tree.getItemInstance("some-id"); |
| 46 | + |
| 47 | +item.getId === item.getId; // This will be true with static instances, but false with proxied instances |
| 48 | +``` |
| 49 | + |
| 50 | +The results of executing those methods will of course not be affected. Don't confuse this with the behavior of |
| 51 | +the [Prop Memoization Feature](/features/propmemoization), which will memoize the props of the tree item functions, |
| 52 | +i.e. the results of calling the `item.getProps()` method, which is not related to this topic. |
0 commit comments