Resource Reform - Githubissues

This is an in-progress pull request that reforms the resource implementation.

Its primary purpose is to separate out the setup phase (the code that runs on initial render that sets up the resource's state) from the synchronization phase (the code that runs outside of the render phase and synchronizes external state with reactive state).

It creates a new low-level primitive: SyncTo. A SyncTo represents code that runs in the sync phase, which corresponds to a framework's structured phase for synchronizing reactive state with external stores. For example, it would correspond to the code in useEffect in React.

This pull request also formalizes the separation between the setup phase (which runs once per component lifetime), the render phase (which runs once per top-level render, including re-render), and the sync phase (which runs during external store synchronization).

Finally, this pull request also retools the lifetime system to be more aligned with JavaScript's Stage 3 Explicit Resource Management API. It's a rather significant internal change, but from a user-facing perspective, it creates the concept of an active Finalization Scope that supplements the existing concept of an active Tracking Frame.

At the primitive level, it's now possible to register a finalization handler with the current finalization scope, and it's also possible to link an object with the current finalization scope. It is also possible to push a new finalization scope, as well as mount an existing finalization scope to collect additional finalizers.

It's still possible to explicitly link objects together and register finalization handlers onto existing objects, but a lot of explicit linking is handled through finalization scopes.

Before this PR is ready, I'll update this text with some additional information about the fact that automatic linking occurs during the setup phase, and how the updated resource API makes structuring code in this way idiomatic.

Current status:

[X] Update lifetime infrastructure
- [X] Move lifetime primitives into @starbeam/shared
[X] Lifetime tests
[X] Sync primitive
[X] Higher level SyncTo
[X] Child synchronization
[X] Sync testing
[X] Resource implementation
[X] Child resources
[X] Resource testing
[ ] ResourceList
[ ] Update Service for new Resource infrastructure
[ ] Integration with existing renderers
- [ ] React
- [ ] Preact
- [ ] Vue
[ ] Garbage collect old resource implementation
[ ] Restore Description infrastructure
[ ] All tests pass (currently ~5~ 4 failing tests)

Follow-ups:

[ ] Good error messages if reactive values are used incorrectly during the resource phases.
[ ] Minimize the surface area of the lifetime infrastructure in @starbeam/shared

🚧 This description, like the PR itself, is under construction. It will be updated as the PR nears completion.

starbeamjs / starbeam

Resource Reform #112