diff --git a/text/1079-ember-reactive.md b/text/1079-ember-reactive.md new file mode 100644 index 0000000000..19a68359e3 --- /dev/null +++ b/text/1079-ember-reactive.md @@ -0,0 +1,484 @@ +--- +stage: accepted +start-date: 2025-03-06T00:00:00.000Z # In format YYYY-MM-DDT00:00:00.000Z +release-date: # In format YYYY-MM-DDT00:00:00.000Z +release-versions: +teams: # delete teams that aren't relevant + - framework + - learning +prs: + accepted: https://github.com/emberjs/rfcs/pull/1079 # Fill this in with the URL for the Proposal RFC PR +project-link: +suite: +--- + + + + + +# Propose a simpler tracked state utility from `@ember/reactive` + +## Summary + +The RFC proposes solving two things: +- import fatigue +- reactive-wrapper fatigue + +by introducing a brand new package (one additional import: `@ember/reactive`) with a named export, `reactive` which allows deep reactivity across all our default reactive data structures in the current blueprint: +- primitive values (only possible via decorator) +- arrays +- objects +- maps +- sets +- weak maps +- weak sets + + + +> [!NOTE] +> It is also possible we can introduce additional defaults in the future. Such as the [promise, proposed (sort of) in RFC #1060](https://github.com/emberjs/rfcs/pull/1060) + +## Motivation + +Example[^example-requires-vm-work]: +```gjs +import { reactive } from '@ember/reactive'; + +const data = reactive({ greeting: 'hi' }); +const exclaim = () => data.greeting += '!'; + +export const Demo = ; +``` + +
class-based example + +Same footnote applies as above[^example-requires-vm-work] + +```gjs +import Component from '@glimmer/component'; +import { reactive } from '@ember/reactive'; + +export class Demo extends Component { + // makes the *reference* reactive + @reactive count = 0; + + // makes the right-hand side of the = reactive + data = reactive({ greeting: 'hello' }); + + // both left and right-hand sides are reactive + @reactive data2 = { greeting: 'hello' }; + + exclaim() { + this.count++; + this.data.greeting += "!"; + this.data2.greeting += "!"; + } + + +} +``` + +
+ +[^example-requires-vm-work]: These examples assume that these RFCs are implemented: [#989: `fn` as a keyword](https://github.com/emberjs/rfcs/pull/998), [#997: `on` as a keyword](https://github.com/emberjs/rfcs/pull/997), [#1070: Default globals for strict mode](https://github.com/emberjs/rfcs/pull/1070), and that the long-standing bug in the VM where plain methods don't work in class-based components is fixed. + +Feedback on prior RFCs, [Tracking utilities for promises](https://github.com/emberjs/rfcs/pull/1060), [The Cell](https://github.com/emberjs/rfcs/pull/1071), and [tracked-built-ins, built-in](https://github.com/emberjs/rfcs/pull/1068), revealed that folks have found that building reactive data structures, by default, is cumbersome. While there utilities would not be removed in anyway, we want to provide a way for folks to make things easily reactive, and _still_ provide a way to get fine-grained reactivity via the existing tools that folks are used to today. + +The main tradeoff with deep reactivity vs explicit / shallow is the impact to memory. This RFC describes those tradeoffs, and provides a way for folks to determine when they may want to consider + +This RFC could, but is not required to, replace: +- [RFC#1068](https://github.com/emberjs/rfcs/pull/1068): tracked-built-ins, built-in + +## Detailed design + +Goals for `reactive`: +- decorator and non-decorator usage (compatible with typescript) +- handles both primitive values and the _common collections_[^the-common-collections] +- shallow by default (current behavior in existing tools) +- optional deeply reactive[^deep-reactivity] (and lazily deeply reactive) + +[^the-common-collections]: The comment collection data structures are: `Array`, `Set`, `WeakSet`, `Object`, `Map`, `WeakMap` +[^deep-reactivity]: this is to make working with nested data easier, and reduce bugs encountered when updating _parts_ of state. The main known cost is to memory, as we have to make use of proxies around every value so we can continue to be deeply reactive, and lazily reactive. + +### Proposed API / available usage + +[Example Types at tsplay.dev](https://www.typescriptlang.org/play/?experimentalDecorators=true&target=99&jsx=0#code/JYWwDg9gTgLgBAbzgUwB5mQYxgFQJ4YDyAZnAL5zFQQhwDkaG2AtDAcnQNwBQ3A9HzgALGDDABnAFwCA5sBhCArgCMAdJhp9kIZcigArcXyjFMRsIoA2lvgEYADAHZbfYsEvJx3YADsYe4gBDTGQ4ACVkYJhgADdkAB4ANUDLRWQAPkRuODhMRSgoZD9JOGTU5B4cwsCAEwAKAEoSsrSeMl5ffxNg0IBhZGsklLTMtH8fGvFwyOxYhJaMrJyBOFU17nbuNgw4AAUoUHk5uABeOB9FHT04AB84cRgDnxlb86tLV8UJ5DcfZBrXsoIBAPIEfDx+IIwJZAr44IpxIEZMhuMQvrMID44NVZnEhuV0nVfBYYM1hsgmqVyShUONJnsDiAjnE4AB+OD9QYLTJk8o8FYPJGhFwAJjgNSw0ECMGgqPR0Ux2Jm0TidRggSgyNJcAgyn0WBgABo4ABrZB4EoPJ4vO7iPA6EHGiXiTAHMAyqCskpfE0+CAAdx8lLBeH5gnETDgghwvQAzABOOAAEUlUGlsrRPgxWJxKvm5MJ2Tg6s1yG1vRh4nEAEFMCEq9AUxo0x6cBqtfEfX7A8bucaixo-GMShXAlXa-XxI3U+moL1Mf5adxKaPx3XPFOoE2pR6IuIrDBOz5fQGfL2CxCVqBodoiuqFVi1exxRBPD46PAQNKusa0FFLHgDRylmD5KlEcz4iMdRrKo7ZSPCx7dj4ADaAC6lJdqeSxKjA+RYvYcBjghJ6BoRUwLG0vCQgING0bRkJwDgngwOIACE1F0ZxfDeEO3QhHAADKNDIIQerYcQwIlBcVxQJUcDKBqUnIHEskbLwKy6vq2DcIwBr4EQxB1Lmcx1EgEkQCUYpkA0DSqDKACy0qYEIolabg7DxGZklvDJ5CEg0YaEQUgR4Dp6B6ewJBGcqJnIXQ5l0OhtkygAogAjooKT6SJxDxFavgyGh-mBV+YBhUw7kGdF4Gqn8-pwI5YB5Y8BXGvlzz+TZdkQOlmWWNlJDxI1zXWm1LUdcVDH+pEJpwKV5URVVxm1cg9UAOozcNQkgCJerGkCIKRD4nXJT1GVZZFuUbYEJpbcJrn7cCoLHZNAplgt2ADYZy3IHUdWCWWI0FSd3W9RdBnxAJgPtTI6SvYI003fc726Z9l3Vbiv3-ddJpQ4e227foIOped-WXfEON45D916nDjSXoIErNrOXiMNA8CYJWUwAGLAthKxAgoYGY0qxB6EU-FggCP1wDE5JFgAAjLGhfPAZz2HJSsxSygSnIglDeVZmsy8oetxQlqHG9roSYHr-3DTDY3WpNORazVoQAmc2ObYETUEw98lPUdLtwG7IuhF7q0A4eMMh2HeaUHbUeU4D-u0-TvDLIIMty+UOo+ABxqFGLhRZqEwBTIK0SYEWLxnD9dQEUR0m6FAAVFkIesN15FlwCK1lycAXfW3U5vAol7c5Pow-u39UcO+NMhO8DjRATks31yP3s3XdO0Bwdz2dXJHyb7P-1U7Hq9ybQp+Y3P60zVTadE1fmdRoIjCWMAmDyMLCfF+LMuhEJh-2OLnNIisZZYlvnmRuZEfKt0nqHGWEAZ53x7pZAekDrZwDAGg2BY8IATytu7OAaV8EmXtr7IGzxl4dVXtg0hUAKErQfjvahz9HqHTBEfRhIspgwMoVHC+i9eGuxlmrUBrC4Ap3xjTF+NlKLcA8PAUgkd6q8wgBnD6lUcp1GIOoCAqtTpgzJhDFuehJqo10VFAxgQTGky+p5cyUlLitz8hnaxX19GqGUA4vqTiYZFU8eFNGVUDGYH8eDHKQ1qGO3uKIqxoSbGGQMTUKJZiYk413oTLhh8kkVW8QYikoNHHkxEc7Api09EGOIBkpxsjqZ71ppNHRRTVAyHqeTTklh4gWKgHTduXj0YGKEF0iGCAXEIOuGQKpYSamqGAOMmJQTUJzJST4-QyzBoL1GgkypITCkjNUCabZV0fZ+3kXk4O6z2mWDOZDaGiTDnVNsaoEADzGnP0GRCYZ4TVBBlKQE7pAxen9J+W045EAHmTO8v0jxQzkntLAA81ZtzjlpQebs1q+zgbov+W3IF0TBrZI4VcwO3CXovPmW88QDyKl4upRsgxMBPmP1TvIiF3AgA) + +
example type tests + +```ts +import { expectTypeOf } from 'expect-type'; + +// https://github.com/emberjs/rfcs/pull/1071/files +interface Reactive { + current: Value; + read(): Value; +} + +interface Cell extends Reactive { + // ... +} + +type Primitive = number | string | null | undefined | boolean; + +// plain usage +function reactive(input: Value): Value extends Primitive ? Cell : Value; +// stage 1/2 decorator +function reactive(target: object, key: string | symbol, descriptor?: unknown): any; +// spec / TC39 Decorator +function reactive( + target: ClassAccessorDecoratorTarget, + context: ClassAccessorDecoratorContext +): ClassAccessorDecoratorResult; + +// implementation (type doesn't matter, exactly) +function reactive(...args: unknown[]): unknown { + return 0 as unknown as Value; +} + + +/////////////// +// Tests! +/////////////// +interface SomeObj { + foo: number; + bar: never; +} + +// object +expectTypeOf(reactive({ foo: 2 })).toMatchObjectType<{ foo: number }>(); +// array +expectTypeOf(reactive(['foo'])).toEqualTypeOf(); +// map +expectTypeOf(reactive(new Map())).toEqualTypeOf>(); +// weak map +expectTypeOf(reactive(new WeakMap())).toEqualTypeOf>(); +// set +expectTypeOf(reactive(new Set())).toEqualTypeOf>(); +// weak set +expectTypeOf(reactive(new WeakSet())).toEqualTypeOf>(); + +// decorators +export class Foo { + // both reactive reference and reactive value + @reactive count = 0; + @reactive a = { foo: 2 }; + @reactive b = ['foo']; + @reactive c = new Map(); + @reactive d = new WeakMap(); + @reactive e = new Set(); + @reactive f = new WeakSet(); + + // reactive value only, reference is static + g = reactive(0 as number); + h = reactive({ foo: 2}); + i = reactive(['foo']); + j = reactive(new Map()) + k = reactive(new WeakMap()); + l = reactive(new Set()); + m = reactive(new WeakSet()); + + // explicit reactive reference and reactive value + @reactive n = reactive(0 as number); + @reactive o = reactive({ foo: 2}); + @reactive p = reactive(['foo']); + @reactive q = reactive(new Map()) + @reactive r = reactive(new WeakMap()); + @reactive s = reactive(new Set()); + @reactive t = reactive(new WeakSet()); +} + +let f = new Foo(); + +expectTypeOf(f.count).toEqualTypeOf(); +expectTypeOf(f.a).toEqualTypeOf<{foo: number }>(); +expectTypeOf(f.b).toEqualTypeOf(); +expectTypeOf(f.c).toEqualTypeOf>(); +expectTypeOf(f.d).toEqualTypeOf>(); +expectTypeOf(f.e).toEqualTypeOf>(); +expectTypeOf(f.f).toEqualTypeOf>(); + +expectTypeOf(f.g).toEqualTypeOf>(); +expectTypeOf(f.h).toEqualTypeOf<{foo: number }>(); +expectTypeOf(f.i).toEqualTypeOf(); +expectTypeOf(f.j).toEqualTypeOf>(); +expectTypeOf(f.k).toEqualTypeOf>(); +expectTypeOf(f.l).toEqualTypeOf>(); +expectTypeOf(f.m).toEqualTypeOf>(); + +expectTypeOf(f.n).toEqualTypeOf>(); +expectTypeOf(f.o).toEqualTypeOf<{foo: number }>(); +expectTypeOf(f.p).toEqualTypeOf(); +expectTypeOf(f.q).toEqualTypeOf>(); +expectTypeOf(f.r).toEqualTypeOf>(); +expectTypeOf(f.s).toEqualTypeOf>(); +expectTypeOf(f.t).toEqualTypeOf>(); +``` + +
+ +### Behavior + +#### What does reading do? + +Starting with a `{{ }}` block, we start reading values. + +when reading a value created by `reactive`, (property on an object, item in a collection, "the value" (of a primitive, via current or via decorator)): +- entangle with the `{{ }}` (keep track of which reactive properties were accessed) + +#### What does setting do? + +- if a `{{ }}` block had previously entangled with a reactive property, the `{{ }}` will re-render. + +### What are the performance concerns? + +TODO +- implement RFC in https://github.com/NullVoxPopuli/ember-deep-tracked +- bench deep vs targeted tracked: + - large data with single reactive access + - change a few things vs change many + - enumerate all properties, deeply + - change a few things vs change many + - enumerate only shallowly + - change a few things vs change many + + + +## How we teach this + + + +### Shallow Tracking + +This type of tracking reactivity will intrument one level of the common collection[^the-common-collections] + +#### With the _common collections_[^the-common-collections] + +Template-only: +- return an object matching the API and prototype of the passed in value + +```gjs +import { reactive } from '@ember/reactive'; + +const initialData = { greeting: 'hello' }; +const exclaim = (data) => data.greeting += '!'; + + +``` + +Class-based: +- return an object matching the API and prototype of the passed in value + +```gjs +import Component from '@glimmer/component'; +import { reactive } from '@ember/reactive'; + +export class Demo extends Component { + data = reactive({ greeting: 'hello' }); + + exclaim() { + this.data.greeting += '!'; + } + + +} +``` + + +#### With primitive values + +Template-only: +- return a [`Cell`](https://github.com/emberjs/rfcs/pull/1071) + +```gjs +import { reactive } from '@ember/reactive'; + +const exclaim = (cell) => cell.current += '!'; + + +``` + +Class-based: +- creates a [`Cell`](https://github.com/emberjs/rfcs/pull/1071), since only decorators can intercept read/writes to primitive values + +```gjs +import Component from '@glimmer/component'; +import { reactive } from '@ember/reactive'; + +export class Demo extends Component { + count = reactive(0); + + increment() { + this.count.current++; + } + + +} +``` + + +#### Decorator + primitive value + +Class based example, functionally the exact same as using `@tracked` today: + +```gjs +import Component from '@glimmer/component'; +import { reactive } from '@ember/reactive'; + +export class Demo extends Component { + @reactive count = 0; + + increment() { + this.count++; + } + + +} +``` + + +### Deep tracking + +This type of tracking reactivity will lazily instrument all nested collections[^the-common-collections] + +#### With the _common collections_[^the-common-collections] + +Template-only: +- return an object matching the API and prototype of the passed in value + +```gjs +import { reactive } from '@ember/reactive'; + +const data = reactive.deep({ stuff: { greeting: 'hello' } }); +const exclaim = () => data.stuff.greeting += '!'; + + +``` + +Class-based: +- return an object matching the API and prototype of the passed in value + +```gjs +import Component from '@glimmer/component'; +import { reactive } from '@ember/reactive'; + +export class Demo extends Component { + data = reactive.deep({ stuff: { greeting: 'hello' } }); + + exclaim() { + this.data.stuff.greeting += '!'; + } + + +} +``` + +## Drawbacks + +- Without typescript, how do you know what type of reactive object do you have? +- With deep reactivity, do you use `structuredClone`? do you clone the keys on maps? + - if so, you could never lookup values, because the keys would be different, if you iterate + - everything is a proxy + - Should a reactive deep object `===` the original? sounds hard + +- If we mutate the existing object, that is expensive + + + +## Alternatives + +1. Don't do `deep` + - without `deep`, wrapping a pojo could be a troll +1. Proceed with [tracked-built-ins, built-in](https://github.com/emberjs/rfcs/pull/1068)