Deprecate A(), the array computed macros, and Ember array use on query param arrays (RFC 1114)

[NullVoxPopuli-ai-agent]

A(), the array computed macros, and Ember array use on query param arrays now have deprecations. These were the parts of RFC 1114 that had none.

How to review

Hide whitespace in the diff. One test file is in a new if block, so most of its lines change only in indentation.

This PR is on top of #21588, and its base branch is nvp/deprecate-mixin-followups. Merge #21588 first.

The tests that are not about Ember arrays moved off A() in #21690, which is merged. This PR holds only the deprecations and the tests about Ember arrays.

RFC:

• Deprecate Ember Array rfcs#1114

Advancement:

• Advance RFC #1114 "Deprecating Ember Array" to Stage Ready for Release rfcs#1140

Guides:

• Add guides for A(), the array computed macros, and query param arrays (RFC 1114) ember-learn/deprecation-app#1439

What RFC 1114 lists, and where each part is

EmberArray, MutableArray, NativeArray   #21588
Enumerable                              #21588
ArrayProxy                              #21579 (merged)
A()                                     this PR
Array computed macros                   this PR

Changes

The three deprecations are available in 7.5.0, are not enabled, and go away in 8.0.0.

• deprecate-ember-array-a: A from @ember/array reports on each call.
• deprecate-array-computed-macros: collect, filter, filterBy, intersect, map, mapBy, max, min, setDiff, sort, sum, union, uniq and uniqBy from @ember/object/computed report when you call them. The message names the macro.
• deprecate-query-param-ember-array: the array value of a query param reports when application code uses an Ember array member on it, for example pushObject or firstObject.

Each macro reports one time for each use. mapBy, filterBy and union called map, filter and uniq before, so they now share private functions with them.

The messages point to native JavaScript and to trackedArray from @ember/reactive/collections.

Where application code can get an Ember array

The implementation can go away in 8.0 only if each of these paths reports before that.

A()                              reports (this PR)
Array computed macros            report (this PR)
Query param default value        reports on Ember array use (this PR)
Query param value from the URL   reports on Ember array use (this PR)
ArrayProxy                       reports (#21579)
The array mixins                 report (#21588)
Data adapter hooks               native arrays now (this PR)

Query param arrays

A controller gets an Ember array for a query param with an array default. pushObject on that array updates the URL, and Array query params can be pushed/popped tests this. So the value stays an Ember array until 8.0, and each Ember array member on it reports when application code uses it. One call from application code gives one report.

Ember does not use these members on a query param array. The full suite with all deprecations on gives a report only in that one test.

The migration is to assign a new array to the property. Array query params can be set and the tracked query param tests cover that.

Data adapter

getFilters, columnsForType, getRecords and getRecordKeywords returned A() as their default. They return [] now, and releaseMethods is a native array. Ember read these values only with native methods and get(records, 'length').

What still uses the internal A

• The array macros, for their results. The macros report.
• ArrayProxy. It reports.
• Query param arrays, as above.

Tests

No test imports from @ember/array/index-internal. This follows the review from @ef4.

• Tests about arrays in general use native arrays or trackedArray. That change is Use native and tracked arrays in tests that are not about Ember arrays #21690.
• Tests about Ember arrays use the public A, expect its deprecation, and do not run when A is removed: tracked Ember array rendering, @each and [] observers and computed chains, the A tests, the array macro tests, the Ember array cases of each and of the conditionals.
• Shared fixtures of the Ember array suites silence the deprecation with ignoreDeprecation, the same way as the ArrayProxy fixtures. A stub of deprecate does not nest, so tests that also expect a deprecation use one expectation that matches both messages.

Not in this PR

• isArray and makeArray from @ember/array. RFC 1114 does not list them.
• The enabled version. Add it when Advance RFC #1114 "Deprecating Ember Array" to Stage Ready for Release rfcs#1140 merges.

Test results

Local runs of the full suite:

default                            9287 pass, 18 skip, 0 fail
ALL_DEPRECATIONS_ENABLED=true      9287 pass, 18 skip, 0 fail
OVERRIDE_DEPRECATION_VERSION=15    7729 pass, 599 skip, 0 fail

eslint on the changed files and tsc --noEmit also pass.

🤖 Generated with Claude Code

[NullVoxPopuli]

most of the PR diff is this file -- which... oof

[NullVoxPopuli]

actually, its all indentation. once you hide whitespace, it's only

[ef4]

I'm not confident that this actually would make it possible for us to remove the implementation after the deprecation period. How do we know none of the internal usages are actually providing user-visible behaviors? If they are, then people using those features are still dependent on EmberA and we won't be able to remove it.

Possibly user-visible internal usages:

• queryParams default array values (in the classic route manager). How are we supposed to remove the EmberA implementation if people keep getting an EmberA (with no deprecation) when they use an array as a default value for a query param?
• same goes for _deserializeQueryParam in the router itself.
• does @ember/debug/data-adapter really need an EmberA? If yes, how are we supposed to remove it later? If no, then we should remove it now.

Also, I don't think any of our tests should use @ember/array/index-internal. Either they're specifically testing EmberA support, so they should use the public API, fire the deprecations, and be guarded explicitly so the tests themselves get removed when the deprecation does. Or they're just testing arrays in general, in which case they should move to native array or trackedArray (most of the examples I reviewed are actually this case, and they only use EmberA out of historical inertia).