feat: adds $state.link rune (#12545)

* feat: adds $state.link rune

* add tests

* types

* docs

* debugger

* lint

* Update .changeset/friendly-rice-confess.md

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>

* Update packages/svelte/src/compiler/phases/2-analyze/index.js

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>

* feedback

* feedback

* feedback

* feedback

* rename link_state to linked_state for grammatical consistency

* oops, victim of find-replace

* no need to store linked_value if setting

* simplify tests

* test behaviour of objects

* update docs

* copy

* more direct example that shows unlinking and relinking

* add callback argument support

* fix

* tidy up

* document callback

---------

Co-authored-by: Simon H <5968653+dummdidumm@users.noreply.github.com>
Co-authored-by: Rich Harris <rich.harris@vercel.com>
pull/12924/head
Dominic Gannaway 1 month ago committed by GitHub
parent f6f0e78cbd
commit 63ec2e2e88
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

@ -0,0 +1,5 @@
---
'svelte': patch
---
feat: add `$state.link` rune

@ -62,6 +62,51 @@ Objects and arrays are made deeply reactive by wrapping them with [`Proxies`](ht
> Only POJOs (plain old JavaScript objects) are made deeply reactive. Reactivity will stop at class boundaries and leave those alone
## `$state.link`
Linked state stays up to date with its input:
```js
let a = $state(0);
let b = $state.link(a);
a = 1;
console.log(a, b); // 1, 1
```
You can temporarily _unlink_ state. It will be _relinked_ when the input value changes:
```js
let a = 1;
let b = 1;
// ---cut---
b = 2; // unlink
console.log(a, b); // 1, 2
a = 3; // relink
console.log(a, b); // 3, 3
```
As with `$state`, if `$state.link` is passed a plain object or array it will be made deeply reactive. If passed an existing state proxy it will be reused, meaning that mutating the linked state will mutate the original. To clone a state proxy, you can use [`$state.snapshot`](#$state-snapshot).
If you pass a callback to `$state.link`, changes to the input value will invoke the callback rather than updating the linked state, allowing you to choose whether to (for example) preserve or discard local changes, or merge incoming changes with local ones:
```js
let { stuff } = $props();
let incoming = $state();
let hasUnsavedChanges = $state(false);
let current = $state.link({ ...stuff }, (stuff) => {
if (hasUnsavedChanges) {
incoming = stuff;
} else {
incoming = null;
current = stuff;
}
});
```
## `$state.raw`
State declared with `$state.raw` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it:

@ -124,6 +124,32 @@ declare namespace $state {
*
* @param initial The initial value
*/
/**
* Declares reactive state that is linked to another value. Local reassignments
* will override the linked value until the linked value changes.
*
* Example:
* ```ts
* let a = $state(0);
* let b = $state.link(a);
* a = 1;
* console.log(a, b); // 1, 1
* b = 2; // unlink
* console.log(a, b); // 1, 2
*
* a = 3; // relink
* console.log(a, b); // 3, 3
* ```
*
* https://svelte-5-preview.vercel.app/docs/runes#$state-link
*
* @param value The linked value
*/
export function link<T>(value: T, callback?: (value: T) => void): T;
export function raw<T>(initial: T): T;
export function raw<T>(): T | undefined;
/**

@ -34,6 +34,7 @@ export function BindDirective(node, context) {
node.name !== 'this' && // bind:this also works for regular variables
(!binding ||
(binding.kind !== 'state' &&
binding.kind !== 'linked_state' &&
binding.kind !== 'raw_state' &&
binding.kind !== 'prop' &&
binding.kind !== 'bindable_prop' &&

@ -169,7 +169,7 @@ export function CallExpression(node, context) {
}
// `$inspect(foo)` or `$derived(foo) should not trigger the `static-state-reference` warning
if (rune === '$inspect' || rune === '$derived') {
if (rune === '$inspect' || rune === '$derived' || rune === '$state.link') {
context.next({ ...context.state, function_depth: context.state.function_depth + 1 });
} else {
context.next();

@ -38,7 +38,10 @@ function validate_export(node, scope, name) {
e.derived_invalid_export(node);
}
if ((binding.kind === 'state' || binding.kind === 'raw_state') && binding.reassigned) {
if (
(binding.kind === 'state' || binding.kind === 'raw_state' || binding.kind === 'linked_state') &&
binding.reassigned
) {
e.state_invalid_export(node);
}
}

@ -99,7 +99,7 @@ export function Identifier(node, context) {
context.state.function_depth === binding.scope.function_depth &&
// If we have $state that can be proxied or frozen and isn't re-assigned, then that means
// it's likely not using a primitive value and thus this warning isn't that helpful.
((binding.kind === 'state' &&
(((binding.kind === 'state' || binding.kind === 'linked_state') &&
(binding.reassigned ||
(binding.initial?.type === 'CallExpression' &&
binding.initial.arguments.length === 1 &&

@ -21,6 +21,7 @@ export function VariableDeclarator(node, context) {
// TODO feels like this should happen during scope creation?
if (
rune === '$state' ||
rune === '$state.link' ||
rune === '$state.raw' ||
rune === '$derived' ||
rune === '$derived.by' ||
@ -32,6 +33,8 @@ export function VariableDeclarator(node, context) {
binding.kind =
rune === '$state'
? 'state'
: rune === '$state.link'
? 'linked_state'
: rune === '$state.raw'
? 'raw_state'
: rune === '$derived' || rune === '$derived.by'

@ -88,7 +88,7 @@ export interface ComponentClientTransformState extends ClientTransformState {
}
export interface StateField {
kind: 'state' | 'raw_state' | 'derived' | 'derived_by';
kind: 'state' | 'raw_state' | 'linked_state' | 'derived' | 'derived_by';
id: PrivateIdentifier;
}

@ -44,6 +44,7 @@ export function ClassBody(node, context) {
const rune = get_rune(definition.value, context.state.scope);
if (
rune === '$state' ||
rune === '$state.link' ||
rune === '$state.raw' ||
rune === '$derived' ||
rune === '$derived.by'
@ -55,6 +56,8 @@ export function ClassBody(node, context) {
? 'state'
: rune === '$state.raw'
? 'raw_state'
: rune === '$state.link'
? 'linked_state'
: rune === '$derived.by'
? 'derived_by'
: 'derived',
@ -116,6 +119,13 @@ export function ClassBody(node, context) {
'$.source',
should_proxy(init, context.state.scope) ? b.call('$.proxy', init) : init
)
: field.kind === 'linked_state'
? b.call(
'$.source_link',
b.thunk(
should_proxy(init, context.state.scope) ? b.call('$.proxy', init) : init
)
)
: field.kind === 'raw_state'
? b.call('$.source', init)
: field.kind === 'derived_by'
@ -133,8 +143,24 @@ export function ClassBody(node, context) {
const member = b.member(b.this, field.id);
body.push(b.prop_def(field.id, value));
if (field.kind === 'linked_state') {
// get foo() { return this.#foo; }
body.push(b.method('get', definition.key, [], [b.return(b.call(member))]));
// set foo(value) { this.#foo = value; }
const value = b.id('value');
body.push(
b.method(
'set',
definition.key,
[value],
[b.stmt(b.call(member, build_proxy_reassignment(value, field.id)))]
)
);
} else {
// get foo() { return this.#foo; }
body.push(b.method('get', definition.key, [], [b.return(b.call('$.get', member))]));
}
if (field.kind === 'state') {
// set foo(value) { this.#foo = value; }

@ -96,7 +96,7 @@ export function Program(_, context) {
if (is_prop_source(binding, context.state)) {
context.state.transform[name] = {
read: b.call,
assign: (node, value) => b.call(node, value),
assign: b.call,
mutate: (node, value) => {
if (binding.kind === 'bindable_prop') {
// only necessary for interop with legacy parent bindings

@ -113,7 +113,7 @@ export function VariableDeclaration(node, context) {
const value =
args.length === 0 ? b.id('undefined') : /** @type {Expression} */ (context.visit(args[0]));
if (rune === '$state' || rune === '$state.raw') {
if (rune === '$state' || rune === '$state.raw' || rune === '$state.link') {
/**
* @param {Identifier} id
* @param {Expression} value
@ -122,12 +122,24 @@ export function VariableDeclaration(node, context) {
const binding = /** @type {import('#compiler').Binding} */ (
context.state.scope.get(id.name)
);
if (rune === '$state' && should_proxy(value, context.state.scope)) {
if (
(rune === '$state' || rune === '$state.link') &&
should_proxy(value, context.state.scope)
) {
value = b.call('$.proxy', value);
}
if (is_state_source(binding, context.state.analysis)) {
if (rune === '$state.link') {
value = b.call(
'$.source_link',
b.thunk(value),
args.length === 2 && /** @type {Expression} */ (context.visit(args[1]))
);
} else if (is_state_source(binding, context.state.analysis)) {
value = b.call('$.source', value);
}
return value;
};

@ -49,5 +49,12 @@ export function add_state_transformers(context) {
}
};
}
if (binding.kind === 'linked_state') {
context.state.transform[name] = {
read: b.call,
assign: b.call
};
}
}
}

@ -11,7 +11,12 @@ export function PropertyDefinition(node, context) {
if (context.state.analysis.runes && node.value != null && node.value.type === 'CallExpression') {
const rune = get_rune(node.value, context.state.scope);
if (rune === '$state' || rune === '$state.raw' || rune === '$derived') {
if (
rune === '$state' ||
rune === '$state.link' ||
rune === '$state.raw' ||
rune === '$derived'
) {
return {
...node,
value:

@ -278,6 +278,7 @@ export interface Binding {
| 'bindable_prop'
| 'rest_prop'
| 'state'
| 'linked_state'
| 'raw_state'
| 'derived'
| 'each'

@ -105,7 +105,7 @@ export {
user_effect,
user_pre_effect
} from './reactivity/effects.js';
export { mutable_source, mutate, source, set } from './reactivity/sources.js';
export { mutable_source, mutate, source, source_link, set } from './reactivity/sources.js';
export {
prop,
rest_props,

@ -26,6 +26,7 @@ import {
MAYBE_DIRTY
} from '../constants.js';
import * as e from '../errors.js';
import { derived } from './deriveds.js';
let inspect_effects = new Set();
@ -45,6 +46,54 @@ export function source(v) {
};
}
/**
* @template V
* @param {() => V} get_value
* @param {(value: V) => void} [callback]
* @returns {(value?: V) => V}
*/
export function source_link(get_value, callback) {
var was_local = false;
var init = false;
var local_source = source(/** @type {V} */ (undefined));
var linked_derived = derived(() => {
var local_value = /** @type {V} */ (get(local_source));
var linked_value = get_value();
if (was_local) {
was_local = false;
return local_value;
}
return linked_value;
});
return function (/** @type {any} */ value) {
if (arguments.length > 0) {
was_local = true;
set(local_source, value);
get(linked_derived);
return value;
}
var linked_value = get(linked_derived);
if (init) {
if (callback !== undefined) {
untrack(() => callback(linked_value));
return local_source.v;
}
} else {
init = true;
}
local_source.v = linked_value;
return linked_value;
};
}
/**
* @template V
* @param {V} initial_value

@ -393,6 +393,7 @@ export function is_mathml(name) {
const RUNES = /** @type {const} */ ([
'$state',
'$state.link',
'$state.raw',
'$state.snapshot',
'$props',

@ -0,0 +1,38 @@
import { flushSync } from 'svelte';
import { test } from '../../test';
export default test({
html: `<button>0</button><button>0</button><button>false</button>`,
test({ assert, target }) {
const [btn1, btn2, btn3] = target.querySelectorAll('button');
flushSync(() => btn1.click());
assert.htmlEqual(
target.innerHTML,
`<button>1</button><button>1</button><button>false</button>`
);
flushSync(() => btn2.click());
assert.htmlEqual(
target.innerHTML,
`<button>1</button><button>2</button><button>false</button>`
);
flushSync(() => btn3.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>2</button><button>true</button>`);
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>2</button><button>2</button><button>true</button>`);
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>3</button><button>2</button><button>true</button>`);
flushSync(() => btn1.click());
flushSync(() => btn3.click());
assert.htmlEqual(
target.innerHTML,
`<button>4</button><button>4</button><button>false</button>`
);
}
});

@ -0,0 +1,12 @@
<script>
let a = $state(0);
let b = $state.link(a, (value) => {
if (c) return;
b = value;
});
let c = $state(false);
</script>
<button onclick={() => a++}>{a}</button>
<button onclick={() => b++}>{b}</button>
<button onclick={() => c = !c}>{c}</button>

@ -0,0 +1,19 @@
import { flushSync } from 'svelte';
import { test } from '../../test';
export default test({
html: `<button>0</button><button>0</button>`,
test({ assert, target }) {
const [btn1, btn2] = target.querySelectorAll('button');
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>1</button>`);
flushSync(() => btn2.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>2</button>`);
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>2</button><button>2</button>`);
}
});

@ -0,0 +1,11 @@
<script>
class Instance {
a = $state(0);
b = $state.link(this.a);
}
const instance = new Instance();
</script>
<button onclick={() => instance.a++}>{instance.a}</button>
<button onclick={() => instance.b++}>{instance.b}</button>

@ -0,0 +1,24 @@
import { flushSync } from 'svelte';
import { test } from '../../test';
export default test({
html: `<button>0</button><button>0</button><button>0</button>`,
test({ assert, target }) {
const [btn1, btn2, btn3] = target.querySelectorAll('button');
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>1</button><button>1</button>`);
// mutate the original object, via the link
flushSync(() => btn2.click());
assert.htmlEqual(target.innerHTML, `<button>2</button><button>2</button><button>2</button>`);
// mutate the copy
flushSync(() => btn3.click());
assert.htmlEqual(target.innerHTML, `<button>2</button><button>2</button><button>3</button>`);
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>3</button><button>3</button><button>3</button>`);
}
});

@ -0,0 +1,9 @@
<script>
let a = $state({ value: 0 });
let b = $state.link(a);
let c = $state.link({ ...a });
</script>
<button onclick={() => a.value++}>{a.value}</button>
<button onclick={() => b.value++}>{b.value}</button>
<button onclick={() => c.value++}>{c.value}</button>

@ -0,0 +1,19 @@
import { flushSync } from 'svelte';
import { test } from '../../test';
export default test({
html: `<button>0</button><button>0</button>`,
test({ assert, target }) {
const [btn1, btn2] = target.querySelectorAll('button');
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>1</button>`);
flushSync(() => btn2.click());
assert.htmlEqual(target.innerHTML, `<button>1</button><button>2</button>`);
flushSync(() => btn1.click());
assert.htmlEqual(target.innerHTML, `<button>2</button><button>2</button>`);
}
});

@ -0,0 +1,7 @@
<script>
let a = $state(0);
let b = $state.link(a);
</script>
<button onclick={() => a++}>{a}</button>
<button onclick={() => b++}>{b}</button>

@ -927,6 +927,7 @@ declare module 'svelte/compiler' {
| 'bindable_prop'
| 'rest_prop'
| 'state'
| 'linked_state'
| 'raw_state'
| 'derived'
| 'each'
@ -2912,6 +2913,32 @@ declare namespace $state {
*
* @param initial The initial value
*/
/**
* Declares reactive state that is linked to another value. Local reassignments
* will override the linked value until the linked value changes.
*
* Example:
* ```ts
* let a = $state(0);
* let b = $state.link(a);
* a = 1;
* console.log(a, b); // 1, 1
* b = 2; // unlink
* console.log(a, b); // 1, 2
*
* a = 3; // relink
* console.log(a, b); // 3, 3
* ```
*
* https://svelte-5-preview.vercel.app/docs/runes#$state-link
*
* @param value The linked value
*/
export function link<T>(value: T, callback?: (value: T) => void): T;
export function raw<T>(initial: T): T;
export function raw<T>(): T | undefined;
/**

@ -118,6 +118,7 @@ const runes = [
{ snippet: '$bindable()', test: is_bindable },
{ snippet: '$effect.root(() => {\n\t${}\n})' },
{ snippet: '$state.snapshot(${})' },
{ snippet: '$state.link(${})' },
{ snippet: '$effect.tracking()' },
{ snippet: '$inspect(${});', test: is_statement }
];

@ -64,6 +64,51 @@ Only plain objects and arrays [are made deeply reactive](/#H4sIAAAAAAAAE42QwWrDM
In non-runes mode, a `let` declaration is treated as reactive state if it is updated at some point. Unlike `$state(...)`, which works anywhere in your app, `let` only behaves this way at the top level of a component.
## `$state.link`
Linked state stays up to date with its input:
```js
let a = $state(0);
let b = $state.link(a);
a = 1;
console.log(a, b); // 1, 1
```
You can temporarily _unlink_ state. It will be _relinked_ when the input value changes:
```js
let a = 1;
let b = 1;
// ---cut---
b = 2; // unlink
console.log(a, b); // 1, 2
a = 3; // relink
console.log(a, b); // 3, 3
```
As with `$state`, if `$state.link` is passed a plain object or array it will be made deeply reactive. If passed an existing state proxy it will be reused, meaning that mutating the linked state will mutate the original. To clone a state proxy, you can use [`$state.snapshot`](#$state-snapshot).
If you pass a callback to `$state.link`, changes to the input value will invoke the callback rather than updating the linked state, allowing you to choose whether to (for example) preserve or discard local changes, or merge incoming changes with local ones:
```js
let { stuff } = $props();
let incoming = $state();
let hasUnsavedChanges = $state(false);
let current = $state.link({ ...stuff }, (stuff) => {
if (hasUnsavedChanges) {
incoming = stuff;
} else {
incoming = null;
current = stuff;
}
});
```
## `$state.raw`
State declared with `$state.raw` cannot be mutated; it can only be _reassigned_. In other words, rather than assigning to a property of an object, or using an array method like `push`, replace the object or array altogether if you'd like to update it:

Loading…
Cancel
Save