diff --git a/documentation/docs/98-reference/21-svelte-reactivity.md b/documentation/docs/98-reference/21-svelte-reactivity.md index 6857c1dba80d..8070331f481b 100644 --- a/documentation/docs/98-reference/21-svelte-reactivity.md +++ b/documentation/docs/98-reference/21-svelte-reactivity.md @@ -2,24 +2,6 @@ title: svelte/reactivity --- -Svelte provides reactive versions of various built-ins like `SvelteMap`, `SvelteSet` and `SvelteURL`. These can be imported from `svelte/reactivity` and used just like their native counterparts. - -```svelte - - - - - - - -
- - - -``` +Svelte provides reactive versions of various built-ins like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map), [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) and [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) that can be used just like their native counterparts, as well as a handful of additional utilities for handling reactivity. > MODULE: svelte/reactivity diff --git a/packages/svelte/src/reactivity/date.js b/packages/svelte/src/reactivity/date.js index 33da2e176159..721673bc36f3 100644 --- a/packages/svelte/src/reactivity/date.js +++ b/packages/svelte/src/reactivity/date.js @@ -5,6 +5,38 @@ import { active_reaction, get, set_active_reaction } from '../internal/client/ru var inited = false; +/** + * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object. + * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) + * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated when the value of the date changes. + * + * ```svelte + * + * + *

The time is {formatter.format(date)}

+ * ``` + */ export class SvelteDate extends Date { #time = source(super.getTime()); diff --git a/packages/svelte/src/reactivity/map.js b/packages/svelte/src/reactivity/map.js index 3fa2945ef08c..3ae8fe5ad19c 100644 --- a/packages/svelte/src/reactivity/map.js +++ b/packages/svelte/src/reactivity/map.js @@ -5,6 +5,47 @@ import { get } from '../internal/client/runtime.js'; import { increment } from './utils.js'; /** + * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object. + * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the map is updated. + * + * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state). + * + * ```svelte + * + * + *
+ * {#each Array(9), i} + * + * {/each} + *
+ * + * {#if winner} + *

{winner} wins!

+ * + * {:else} + *

{player} is next

+ * {/if} + * ``` + * * @template K * @template V * @extends {Map} diff --git a/packages/svelte/src/reactivity/set.js b/packages/svelte/src/reactivity/set.js index be0c2d2cf5d6..4a0b4dfdb398 100644 --- a/packages/svelte/src/reactivity/set.js +++ b/packages/svelte/src/reactivity/set.js @@ -10,6 +10,37 @@ var set_like_methods = ['difference', 'intersection', 'symmetricDifference', 'un var inited = false; /** + * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object. + * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the set is updated. + * + * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state). + * + * ```svelte + * + * + * {#each ['🙈', '🙉', '🙊'] as monkey} + * + * {/each} + * + * + * + * {#if monkeys.has('🙈')}

see no evil

{/if} + * {#if monkeys.has('🙉')}

hear no evil

{/if} + * {#if monkeys.has('🙊')}

speak no evil

{/if} + * ``` + * * @template T * @extends {Set} */ diff --git a/packages/svelte/src/reactivity/url-search-params.js b/packages/svelte/src/reactivity/url-search-params.js index 13f697199643..c1a8275f150b 100644 --- a/packages/svelte/src/reactivity/url-search-params.js +++ b/packages/svelte/src/reactivity/url-search-params.js @@ -5,6 +5,32 @@ import { increment } from './utils.js'; export const REPLACE = Symbol(); +/** + * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object. + * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the params are updated. + * + * ```svelte + * + * + * + * + * + * + *

?{params.toString()}

+ * + * {#each params as [key, value]} + *

{key}: {value}

+ * {/each} + * ``` + */ export class SvelteURLSearchParams extends URLSearchParams { #version = source(0); #url = get_current_url(); @@ -23,6 +49,7 @@ export class SvelteURLSearchParams extends URLSearchParams { /** * @param {URLSearchParams} params + * @internal */ [REPLACE](params) { if (this.#updating) return; diff --git a/packages/svelte/src/reactivity/url.js b/packages/svelte/src/reactivity/url.js index 5d003be0210a..879006f057dc 100644 --- a/packages/svelte/src/reactivity/url.js +++ b/packages/svelte/src/reactivity/url.js @@ -10,6 +10,33 @@ export function get_current_url() { return current_url; } +/** + * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object. + * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the URL changes. + * + * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams). + * + * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a): + * + * ```svelte + * + * + * + * + * + * + * + *
+ * + * + * + * ``` + */ export class SvelteURL extends URL { #protocol = source(super.protocol); #username = source(super.username); diff --git a/packages/svelte/types/index.d.ts b/packages/svelte/types/index.d.ts index c6000fc4b67f..eec4cc0f8705 100644 --- a/packages/svelte/types/index.d.ts +++ b/packages/svelte/types/index.d.ts @@ -1898,11 +1898,77 @@ declare module 'svelte/motion' { } declare module 'svelte/reactivity' { + /** + * A reactive version of the built-in [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) object. + * Reading the date (whether with methods like `date.getTime()` or `date.toString()`, or via things like [`Intl.DateTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat)) + * in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated when the value of the date changes. + * + * ```svelte + * + * + *

The time is {formatter.format(date)}

+ * ``` + */ export class SvelteDate extends Date { constructor(...params: any[]); #private; } + /** + * A reactive version of the built-in [`Set`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) object. + * Reading contents of the set (by iterating, or by reading `set.size` or calling `set.has(...)` as in the [example](https://svelte.dev/playground/53438b51194b4882bcc18cddf9f96f15) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the set is updated. + * + * Note that values in a reactive set are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state). + * + * ```svelte + * + * + * {#each ['🙈', '🙉', '🙊'] as monkey} + * + * {/each} + * + * + * + * {#if monkeys.has('🙈')}

see no evil

{/if} + * {#if monkeys.has('🙉')}

hear no evil

{/if} + * {#if monkeys.has('🙊')}

speak no evil

{/if} + * ``` + * + * + */ export class SvelteSet extends Set { constructor(value?: Iterable | null | undefined); @@ -1910,6 +1976,50 @@ declare module 'svelte/reactivity' { add(value: T): this; #private; } + /** + * A reactive version of the built-in [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) object. + * Reading contents of the map (by iterating, or by reading `map.size` or calling `map.get(...)` or `map.has(...)` as in the [tic-tac-toe example](https://svelte.dev/playground/0b0ff4aa49c9443f9b47fe5203c78293) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the map is updated. + * + * Note that values in a reactive map are _not_ made [deeply reactive](https://svelte.dev/docs/svelte/$state#Deep-state). + * + * ```svelte + * + * + *
+ * {#each Array(9), i} + * + * {/each} + *
+ * + * {#if winner} + *

{winner} wins!

+ * + * {:else} + *

{player} is next

+ * {/if} + * ``` + * + * + */ export class SvelteMap extends Map { constructor(value?: Iterable | null | undefined); @@ -1917,11 +2027,64 @@ declare module 'svelte/reactivity' { set(key: K, value: V): this; #private; } + /** + * A reactive version of the built-in [`URL`](https://developer.mozilla.org/en-US/docs/Web/API/URL) object. + * Reading properties of the URL (such as `url.href` or `url.pathname`) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the URL changes. + * + * The `searchParams` property is an instance of [SvelteURLSearchParams](https://svelte.dev/docs/svelte/svelte-reactivity#SvelteURLSearchParams). + * + * [Example](https://svelte.dev/playground/5a694758901b448c83dc40dc31c71f2a): + * + * ```svelte + * + * + * + * + * + * + * + *
+ * + * + * + * ``` + */ export class SvelteURL extends URL { get searchParams(): SvelteURLSearchParams; #private; } const REPLACE: unique symbol; + /** + * A reactive version of the built-in [`URLSearchParams`](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams) object. + * Reading its contents (by iterating, or by calling `params.get(...)` or `params.getAll(...)` as in the [example](https://svelte.dev/playground/b3926c86c5384bab9f2cf993bc08c1c8) below) in an [effect](https://svelte.dev/docs/svelte/$effect) or [derived](https://svelte.dev/docs/svelte/$derived) + * will cause it to be re-evaluated as necessary when the params are updated. + * + * ```svelte + * + * + * + * + * + * + *

?{params.toString()}

+ * + * {#each params as [key, value]} + *

{key}: {value}

+ * {/each} + * ``` + */ export class SvelteURLSearchParams extends URLSearchParams { [REPLACE](params: URLSearchParams): void;