Skip to content

Commit 10a111f

Browse files
committed
Update wording to make it more clear that tracking is preferred
1 parent c541b3b commit 10a111f

File tree

1 file changed

+15
-9
lines changed

1 file changed

+15
-9
lines changed

content/ember/v6/deprecate-array-proxy.md

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ until: 7.0.0
44
since: 6.5.0
55
---
66

7-
`ArrayProxy` is deprecated. In modern Ember, you should use tracked arrays and modern patterns instead. The best replacement depends on how you were using `ArrayProxy`. Some example use cases are shown below.
7+
8+
`ArrayProxy` is deprecated. In modern Ember, you should use tracking primitives—such as tracked arrays and tracked properties—whenever possible. This is almost always the best approach going forward. Some of the examples below demonstrate alternatives using proxies or advanced patterns, but these are generally not ideal. You should strongly consider refactoring your code to use tracking if at all possible, as it leads to simpler, more maintainable, and idiomatic Ember code. However, the best replacement depends on how you were using `ArrayProxy`. Some example use cases are shown below.
89

910
## Recommended: Use Tracked Arrays
1011

@@ -24,13 +25,15 @@ pets.length; // 4
2425

2526
This provides automatic tracking without the complexity of proxies and follows modern Ember patterns.
2627

28+
2729
## Advanced Use Cases
2830

29-
If you need more advanced behavior like content swapping or transformation, you can use the approaches below.
31+
If you need more advanced behavior like content swapping or transformation, you can use the approaches below. However, these patterns are generally not recommended unless you have a strong reason not to use tracked arrays and properties. In most cases, refactoring to use tracking primitives will result in better, more future-proof code.
3032

3133
### Swapping Content
3234

33-
If you were using `ArrayProxy` to easily swap out the underlying array while keeping a stable reference, you can achieve a similar, transparent effect using a native `Proxy` backed by a class with a `@tracked` property.
35+
36+
If you were using `ArrayProxy` to easily swap out the underlying array while keeping a stable reference, you can achieve a similar, transparent effect using a native `Proxy` backed by a class with a `@tracked` property. Again, prefer tracked arrays and properties if you can refactor your code to use them.
3437

3538
Before:
3639

@@ -112,7 +115,8 @@ pets.length; // 2
112115

113116
### Transforming Content
114117

115-
If you were using `objectAtContent` to transform the array's content, you can use a native JavaScript `Proxy` to achieve the same result with standard array syntax.
118+
119+
If you were using `objectAtContent` to transform the array's content, you can use a native JavaScript `Proxy` to achieve the same result with standard array syntax. This is an advanced pattern and should only be used if refactoring to tracked properties is not feasible.
116120

117121
Before:
118122

@@ -214,7 +218,8 @@ manager.people.push({ name: 'Chris' });
214218
manager.arrangedContent[0].name; // 'Chris'
215219
```
216220

217-
For more complex use cases where you need a native `Proxy` for dynamic behavior:
221+
222+
For more complex use cases where you need a native `Proxy` for dynamic behavior, you can use the following pattern. However, this is rarely necessary and should be avoided if you can use tracked properties and computed values instead:
218223

219224
```javascript
220225
// The original data, which can be mutated.
@@ -258,10 +263,11 @@ peopleProxy.arranged[0].name; // 'Chris'
258263

259264
## Migration Strategy
260265

266+
261267
When migrating from `ArrayProxy`, consider:
262268

263-
1. **First choice**: Use `TrackedArray` from `tracked-built-ins` for automatic reactivity
264-
2. **For computed arrays**: Use `@cached` getters with tracked data
265-
3. **Only if needed**: Use native `Proxy` for complex dynamic behavior that can't be achieved with tracked properties
269+
1. **First choice (strongly recommended)**: Use `TrackedArray` from `tracked-built-ins` and tracked properties for automatic reactivity and idiomatic Ember code.
270+
2. **For computed arrays**: Use `@cached` getters with tracked data.
271+
3. **Only if truly necessary**: Use native `Proxy` for complex dynamic behavior that cannot be achieved with tracked properties. This should be rare.
266272

267-
The modern Ember approach favors explicit tracking and computed properties over proxy-based solutions, which are easier to understand, debug, and optimize.
273+
The modern Ember approach strongly favors explicit tracking and computed properties over proxy-based solutions. Tracking primitives are easier to understand, debug, and optimize, and will be the best choice for almost all use cases going forward.

0 commit comments

Comments
 (0)