From d52c7f93a61addf74ac9f7f7e86a1456d631b89f Mon Sep 17 00:00:00 2001 From: Boris Petrov Date: Wed, 13 Aug 2025 14:08:37 +0300 Subject: [PATCH 1/5] Add a `skipCopy` option to tracked-collections --- ...skip-copy-option-to-tracked-collections.md | 62 +++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 text/0000-add-skip-copy-option-to-tracked-collections.md diff --git a/text/0000-add-skip-copy-option-to-tracked-collections.md b/text/0000-add-skip-copy-option-to-tracked-collections.md new file mode 100644 index 0000000000..c4ad5be2bf --- /dev/null +++ b/text/0000-add-skip-copy-option-to-tracked-collections.md @@ -0,0 +1,62 @@ +--- +stage: accepted +start-date: 2025-08-13T14:00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: + - framework +prs: + accepted: # Fill this in with the URL for the Proposal RFC PR +project-link: +suite: +--- + + + + + +# Add a `skipCopy` option to tracked-collections + +## Summary + +Add an option for all tracked-collections (like `TrackedArray`, `TrackedMap` and `TrackedObject`) so that their constructors don't perform a copy of the passed-in collection. + +## Motivation + +That would allow users who know what they're doing to skip a potentially expensive copy of a big collection. + +## Detailed design + +The classes that implement the tracked-collections have an `options` argument. We can add an option to it to skip copying the collection argument that is passed. + +The naming is of course the biggest issue. One might argue that it's good to have "unsafe" in the name because that really is unsafe - if the original collection is modified and it is not copied - that change will not be reflected in the template which might be confusing for the user. On the other hand, this is somewhat "obvious" so naming it "unsafe" might prevent people from using it and therefore skipping on potential (big) performance gains. + +There is a [PR](https://github.com/glimmerjs/glimmer-vm/pull/1767) in the Glimmer VM repo for an implementation in `TrackedArray`. + +## How we teach this + +We add it to the documentation. And also to the TypeScript types (which is already done in the PR above). + +## Drawbacks + +Potential confusion in people why their templates are not modified when the original collection is modified. + +## Alternatives + +I don't think there are. For the best performance, no copy should be made. + +## Unresolved questions + +None. From 5bf9ab1a25dd287818c47c98517018c1435e4cb5 Mon Sep 17 00:00:00 2001 From: Boris Petrov Date: Wed, 13 Aug 2025 15:09:11 +0300 Subject: [PATCH 2/5] Use camelCase names for the tracked-collections --- text/0000-add-skip-copy-option-to-tracked-collections.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-add-skip-copy-option-to-tracked-collections.md b/text/0000-add-skip-copy-option-to-tracked-collections.md index c4ad5be2bf..aa540768d7 100644 --- a/text/0000-add-skip-copy-option-to-tracked-collections.md +++ b/text/0000-add-skip-copy-option-to-tracked-collections.md @@ -31,7 +31,7 @@ suite: Leave as is ## Summary -Add an option for all tracked-collections (like `TrackedArray`, `TrackedMap` and `TrackedObject`) so that their constructors don't perform a copy of the passed-in collection. +Add an option for all tracked-collections (like `trackedArray`, `trackedMap` and `trackedObject`) so that their constructors don't perform a copy of the passed-in collection. ## Motivation @@ -43,7 +43,7 @@ The classes that implement the tracked-collections have an `options` argument. W The naming is of course the biggest issue. One might argue that it's good to have "unsafe" in the name because that really is unsafe - if the original collection is modified and it is not copied - that change will not be reflected in the template which might be confusing for the user. On the other hand, this is somewhat "obvious" so naming it "unsafe" might prevent people from using it and therefore skipping on potential (big) performance gains. -There is a [PR](https://github.com/glimmerjs/glimmer-vm/pull/1767) in the Glimmer VM repo for an implementation in `TrackedArray`. +There is a [PR](https://github.com/glimmerjs/glimmer-vm/pull/1767) in the Glimmer VM repo for an implementation in `trackedArray`. ## How we teach this From 4bda5309e80038300526775d69ee63dc0f9b359d Mon Sep 17 00:00:00 2001 From: Boris Petrov Date: Fri, 15 Aug 2025 10:53:47 +0300 Subject: [PATCH 3/5] Add example names --- ...00-add-skip-copy-option-to-tracked-collections.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/text/0000-add-skip-copy-option-to-tracked-collections.md b/text/0000-add-skip-copy-option-to-tracked-collections.md index aa540768d7..2e7c1e452e 100644 --- a/text/0000-add-skip-copy-option-to-tracked-collections.md +++ b/text/0000-add-skip-copy-option-to-tracked-collections.md @@ -43,6 +43,18 @@ The classes that implement the tracked-collections have an `options` argument. W The naming is of course the biggest issue. One might argue that it's good to have "unsafe" in the name because that really is unsafe - if the original collection is modified and it is not copied - that change will not be reflected in the template which might be confusing for the user. On the other hand, this is somewhat "obvious" so naming it "unsafe" might prevent people from using it and therefore skipping on potential (big) performance gains. +Example names: + +```ts +trackedArray(original, { copy: false }); +trackedArray(original, { copySource: false }); +trackedArray(original, { copyUpstream: false }); + +trackedArray(original, { avoidCopy: true }); +trackedArray(original, { skipCopy: true }); +trackedArray(original, { noCopy: true }); +``` + There is a [PR](https://github.com/glimmerjs/glimmer-vm/pull/1767) in the Glimmer VM repo for an implementation in `trackedArray`. ## How we teach this From 327b9bc4d936fcda44fec71bbfe63fd563ac85b7 Mon Sep 17 00:00:00 2001 From: Boris Petrov Date: Fri, 15 Aug 2025 10:54:08 +0300 Subject: [PATCH 4/5] Remove trailing whitespace --- text/0000-add-skip-copy-option-to-tracked-collections.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-add-skip-copy-option-to-tracked-collections.md b/text/0000-add-skip-copy-option-to-tracked-collections.md index 2e7c1e452e..00114efa7a 100644 --- a/text/0000-add-skip-copy-option-to-tracked-collections.md +++ b/text/0000-add-skip-copy-option-to-tracked-collections.md @@ -8,11 +8,11 @@ teams: prs: accepted: # Fill this in with the URL for the Proposal RFC PR project-link: -suite: +suite: --- -