Skip to content

rfc-1068 - Update the collections to be under the /collections path #1138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kategengler merged 2 commits into from
Aug 22, 2025
Merged

rfc-1068 - Update the collections to be under the /collections path #1138

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9a55e8c
rfc-1068 - Update the collections to be under the /collections path
NullVoxPopuli Aug 17, 2025
a82818c
Update 1068-tracked-collections.md
NullVoxPopuli Aug 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 27 additions & 10 deletions text/1068-tracked-collections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ import {
trackedObject, trackedArray,
trackedMap, trackedWeakMap,
trackedSet, trackedWeakSet
} from '@ember/reactive';
} from '@ember/reactive/collections';
```

### `trackedObject`, `trackedArray`, `trackedMap`, etc
Expand Down Expand Up @@ -150,7 +150,7 @@ Some examples assuming implementation of [RFC#998: Make fn built-in in strict-mo


```gjs
import { trackedArray } from '@ember/reactive';
import { trackedArray } from '@ember/reactive/collections';

const nonTrackedArray = [1, 2, 3];
const addTo = (arr) => arr.push(Math.random());
Expand Down Expand Up @@ -188,7 +188,7 @@ const addTo = (arr) => arr.push(Math.random());
#### Example `trackedObject`

```gjs
import { trackedObject } from '@ember/reactive';
import { trackedObject } from '@ember/reactive/collections';

const nonTrackedObject = { a: 1 };
const addTo = (obj) => obj[Math.random()] = Math.random();
Expand Down Expand Up @@ -249,6 +249,23 @@ For example, other future exports from `@ember/reactive` (in future RFCs), may i
without the static analysis guarantees of `type=module`, every consumer of `@ember/reactive` would always have all of these exports in their build.
For some utilities, we can place them under sub-path-exports, such as `@ember/reactive/window`, for window-specific reactive properties, but the exact specifics of each of these can be hashed out in their individual RFCs.

#### Why are the collections under `@ember/reactive/collections`?

Placing the collections in the main export surface alongside core primitives like `tracked`, `cached`, `cell`, and `resource` may not conflate importance of the collections.

> [!NOTE]
> At the time of writing of this RFC, `tracked`, `cached`, `cell`, and `resource` RFCs have not been accepted for inclusion in `@ember/reactive`

This is motivated by actual usage out in the ecosystem of tracked-built-ins:

here are results from github.com searches for the `tracked-built-ins` equivalents (excluding ember-owned repos and forks of them):
- "new TrackedObject(" - [520 Results]([https://github.com/search?q=%22new+TrackedObject%28%22&type=code](https://github.com/search?q=%22new+TrackedObject%28%22+NOT+is%3Afork++NOT+org%3Aemberjs+NOT+org%3Atracked-tools+NOT+org%3Aember-cli+NOT+org%3Aember-migration-utils+NOT+org%3Aember-learn&type=code))
- "new TrackedArray(" - [312 Results](https://github.com/search?q=%22new+TrackedArray%28%22+NOT+is%3Afork++NOT+org%3Aemberjs+NOT+org%3Atracked-tools+NOT+org%3Aember-cli+NOT+org%3Aember-migration-utils+NOT+org%3Aember-learn+&type=code)
- "new TrackedSet(" - [74 Results](https://github.com/search?q=%22new+TrackedSet%28%22+NOT+is%3Afork++NOT+org%3Aemberjs+NOT+org%3Atracked-tools+NOT+org%3Aember-cli+NOT+org%3Aember-migration-utils+NOT+org%3Aember-learn+&type=code)
- "new TrackedWeakSet(" - [5 Results](https://github.com/search?q=%22new+TrackedWeakSet%28%22+NOT+is%3Afork++NOT+org%3Aemberjs+NOT+org%3Atracked-tools+NOT+org%3Aember-cli+NOT+org%3Aember-migration-utils+NOT+org%3Aember-learn+&type=code)
- "new TrackedWeakMap(" - [4 Results](https://github.com/search?q=%22new+TrackedWeakMap%28%22+NOT+is%3Afork++NOT+org%3Aemberjs+NOT+org%3Atracked-tools+NOT+org%3Aember-cli+NOT+org%3Aember-migration-utils+NOT+org%3Aember-learn+&type=code)

Additionally, specifying collections gives us a blessed path for exported other useful datastructures in the future without continually adding to the main export file (even though dead-code-elimination would eliminate what is unused - not importing what may not be used could help local development)
Copy link
Member

@kategengler kategengler Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it be @ember/reactive/data-structures?

Copy link
Contributor Author

@NullVoxPopuli NullVoxPopuli Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe, but I didn't want to sound too computer sciency

Copy link
Member

@kategengler kategengler Aug 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😆 Maps,Sets,WeakMaps and WeakSets ... not at all computer science-y


### Consumption

Expand All @@ -275,7 +292,7 @@ A utility for creating tracked arrays, copying the original data so that mutatio
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)

```gjs
import { trackedArray } from '@ember/reactive';
import { trackedArray } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand All @@ -302,7 +319,7 @@ A utility for creating tracked objects, copying the original data so that mutati
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)

```gjs
import { trackedObject } from '@ember/reactive';
import { trackedObject } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand All @@ -329,7 +346,7 @@ A utility for creating tracked maps, copying the original data so that mutations
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)

```gjs
import { trackedMap } from '@ember/reactive';
import { trackedMap } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand Down Expand Up @@ -357,7 +374,7 @@ A utility for creating tracked weak maps, copying the original data so that muta
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap)

```gjs
import { trackedWeakMap } from '@ember/reactive';
import { trackedWeakMap } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand All @@ -381,7 +398,7 @@ A utility for creating tracked maps, copying the original data so that mutations
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set)

```gjs
import { trackedSet } from '@ember/reactive';
import { trackedSet } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand Down Expand Up @@ -409,7 +426,7 @@ A utility for creating tracked weak sets, copying the original data so that muta
See [MDN for more information](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet)

```gjs
import { trackedWeakSet } from '@ember/reactive';
import { trackedWeakSet } from '@ember/reactive/collections';
import { on } from '@ember/modifier';
import { fn } from '@ember/helper';

Expand Down Expand Up @@ -470,7 +487,7 @@ We should do a codemod to convert the newable constructors from tracked-built-in
Using Vite or Webpack (Embroider 3+), we can alias `tracked-built-ins` to point at the new modules, using a shim -- for example:
```js
// app/built-ins-shim.js
import { trackedArray } from '@ember/reactive';
import { trackedArray } from '@ember/reactive/collections';

export class TrackedArray {
constructor(arr) {
Expand Down