@depup/svelte 5.53.3-depup.0

package/src/internal/client/reactivity/effects.js

@@ -0,0 +1,718 @@
+/** @import { Blocker, ComponentContext, ComponentContextLegacy, Derived, Effect, TemplateNode, TransitionManager } from '#client' */
+import {
+	is_dirty,
+	active_effect,
+	active_reaction,
+	update_effect,
+	get,
+	is_destroying_effect,
+	remove_reactions,
+	set_active_reaction,
+	set_is_destroying_effect,
+	untrack,
+	untracking
+} from '../runtime.js';
+import {
+	DIRTY,
+	BRANCH_EFFECT,
+	RENDER_EFFECT,
+	EFFECT,
+	DESTROYED,
+	INERT,
+	REACTION_RAN,
+	BLOCK_EFFECT,
+	ROOT_EFFECT,
+	EFFECT_TRANSPARENT,
+	DERIVED,
+	CLEAN,
+	EAGER_EFFECT,
+	HEAD_EFFECT,
+	MAYBE_DIRTY,
+	EFFECT_PRESERVED,
+	STALE_REACTION,
+	USER_EFFECT,
+	ASYNC,
+	CONNECTED,
+	MANAGED_EFFECT
+} from '#client/constants';
+import * as e from '../errors.js';
+import { DEV } from 'esm-env';
+import { define_property } from '../../shared/utils.js';
+import { get_next_sibling } from '../dom/operations.js';
+import { component_context, dev_current_component_function, dev_stack } from '../context.js';
+import { Batch, schedule_effect } from './batch.js';
+import { flatten, increment_pending } from './async.js';
+import { without_reactive_context } from '../dom/elements/bindings/shared.js';
+import { set_signal_status } from './status.js';
+
+/**
+ * @param {'$effect' | '$effect.pre' | '$inspect'} rune
+ */
+export function validate_effect(rune) {
+	if (active_effect === null) {
+		if (active_reaction === null) {
+			e.effect_orphan(rune);
+		}
+
+		e.effect_in_unowned_derived();
+	}
+
+	if (is_destroying_effect) {
+		e.effect_in_teardown(rune);
+	}
+}
+
+/**
+ * @param {Effect} effect
+ * @param {Effect} parent_effect
+ */
+function push_effect(effect, parent_effect) {
+	var parent_last = parent_effect.last;
+	if (parent_last === null) {
+		parent_effect.last = parent_effect.first = effect;
+	} else {
+		parent_last.next = effect;
+		effect.prev = parent_last;
+		parent_effect.last = effect;
+	}
+}
+
+/**
+ * @param {number} type
+ * @param {null | (() => void | (() => void))} fn
+ * @param {boolean} sync
+ * @returns {Effect}
+ */
+function create_effect(type, fn, sync) {
+	var parent = active_effect;
+
+	if (DEV) {
+		// Ensure the parent is never an inspect effect
+		while (parent !== null && (parent.f & EAGER_EFFECT) !== 0) {
+			parent = parent.parent;
+		}
+	}
+
+	if (parent !== null && (parent.f & INERT) !== 0) {
+		type |= INERT;
+	}
+
+	/** @type {Effect} */
+	var effect = {
+		ctx: component_context,
+		deps: null,
+		nodes: null,
+		f: type | DIRTY | CONNECTED,
+		first: null,
+		fn,
+		last: null,
+		next: null,
+		parent,
+		b: parent && parent.b,
+		prev: null,
+		teardown: null,
+		wv: 0,
+		ac: null
+	};
+
+	if (DEV) {
+		effect.component_function = dev_current_component_function;
+	}
+
+	if (sync) {
+		try {
+			update_effect(effect);
+		} catch (e) {
+			destroy_effect(effect);
+			throw e;
+		}
+	} else if (fn !== null) {
+		schedule_effect(effect);
+	}
+
+	/** @type {Effect | null} */
+	var e = effect;
+
+	// if an effect has already ran and doesn't need to be kept in the tree
+	// (because it won't re-run, has no DOM, and has no teardown etc)
+	// then we skip it and go to its child (if any)
+	if (
+		sync &&
+		e.deps === null &&
+		e.teardown === null &&
+		e.nodes === null &&
+		e.first === e.last && // either `null`, or a singular child
+		(e.f & EFFECT_PRESERVED) === 0
+	) {
+		e = e.first;
+		if ((type & BLOCK_EFFECT) !== 0 && (type & EFFECT_TRANSPARENT) !== 0 && e !== null) {
+			e.f |= EFFECT_TRANSPARENT;
+		}
+	}
+
+	if (e !== null) {
+		e.parent = parent;
+
+		if (parent !== null) {
+			push_effect(e, parent);
+		}
+
+		// if we're in a derived, add the effect there too
+		if (
+			active_reaction !== null &&
+			(active_reaction.f & DERIVED) !== 0 &&
+			(type & ROOT_EFFECT) === 0
+		) {
+			var derived = /** @type {Derived} */ (active_reaction);
+			(derived.effects ??= []).push(e);
+		}
+	}
+
+	return effect;
+}
+
+/**
+ * Internal representation of `$effect.tracking()`
+ * @returns {boolean}
+ */
+export function effect_tracking() {
+	return active_reaction !== null && !untracking;
+}
+
+/**
+ * @param {() => void} fn
+ */
+export function teardown(fn) {
+	const effect = create_effect(RENDER_EFFECT, null, false);
+	set_signal_status(effect, CLEAN);
+	effect.teardown = fn;
+	return effect;
+}
+
+/**
+ * Internal representation of `$effect(...)`
+ * @param {() => void | (() => void)} fn
+ */
+export function user_effect(fn) {
+	validate_effect('$effect');
+
+	if (DEV) {
+		define_property(fn, 'name', {
+			value: '$effect'
+		});
+	}
+
+	// Non-nested `$effect(...)` in a component should be deferred
+	// until the component is mounted
+	var flags = /** @type {Effect} */ (active_effect).f;
+	var defer = !active_reaction && (flags & BRANCH_EFFECT) !== 0 && (flags & REACTION_RAN) === 0;
+
+	if (defer) {
+		// Top-level `$effect(...)` in an unmounted component — defer until mount
+		var context = /** @type {ComponentContext} */ (component_context);
+		(context.e ??= []).push(fn);
+	} else {
+		// Everything else — create immediately
+		return create_user_effect(fn);
+	}
+}
+
+/**
+ * @param {() => void | (() => void)} fn
+ */
+export function create_user_effect(fn) {
+	return create_effect(EFFECT | USER_EFFECT, fn, false);
+}
+
+/**
+ * Internal representation of `$effect.pre(...)`
+ * @param {() => void | (() => void)} fn
+ * @returns {Effect}
+ */
+export function user_pre_effect(fn) {
+	validate_effect('$effect.pre');
+	if (DEV) {
+		define_property(fn, 'name', {
+			value: '$effect.pre'
+		});
+	}
+	return create_effect(RENDER_EFFECT | USER_EFFECT, fn, true);
+}
+
+/** @param {() => void | (() => void)} fn */
+export function eager_effect(fn) {
+	return create_effect(EAGER_EFFECT, fn, true);
+}
+
+/**
+ * Internal representation of `$effect.root(...)`
+ * @param {() => void | (() => void)} fn
+ * @returns {() => void}
+ */
+export function effect_root(fn) {
+	Batch.ensure();
+	const effect = create_effect(ROOT_EFFECT | EFFECT_PRESERVED, fn, true);
+
+	return () => {
+		destroy_effect(effect);
+	};
+}
+
+/**
+ * An effect root whose children can transition out
+ * @param {() => void} fn
+ * @returns {(options?: { outro?: boolean }) => Promise<void>}
+ */
+export function component_root(fn) {
+	Batch.ensure();
+	const effect = create_effect(ROOT_EFFECT | EFFECT_PRESERVED, fn, true);
+
+	return (options = {}) => {
+		return new Promise((fulfil) => {
+			if (options.outro) {
+				pause_effect(effect, () => {
+					destroy_effect(effect);
+					fulfil(undefined);
+				});
+			} else {
+				destroy_effect(effect);
+				fulfil(undefined);
+			}
+		});
+	};
+}
+
+/**
+ * @param {() => void | (() => void)} fn
+ * @returns {Effect}
+ */
+export function effect(fn) {
+	return create_effect(EFFECT, fn, false);
+}
+
+/**
+ * Internal representation of `$: ..`
+ * @param {() => any} deps
+ * @param {() => void | (() => void)} fn
+ */
+export function legacy_pre_effect(deps, fn) {
+	var context = /** @type {ComponentContextLegacy} */ (component_context);
+
+	/** @type {{ effect: null | Effect, ran: boolean, deps: () => any }} */
+	var token = { effect: null, ran: false, deps };
+
+	context.l.$.push(token);
+
+	token.effect = render_effect(() => {
+		deps();
+
+		// If this legacy pre effect has already run before the end of the reset, then
+		// bail out to emulate the same behavior.
+		if (token.ran) return;
+
+		token.ran = true;
+		untrack(fn);
+	});
+}
+
+export function legacy_pre_effect_reset() {
+	var context = /** @type {ComponentContextLegacy} */ (component_context);
+
+	render_effect(() => {
+		// Run dirty `$:` statements
+		for (var token of context.l.$) {
+			token.deps();
+
+			var effect = token.effect;
+
+			// If the effect is CLEAN, then make it MAYBE_DIRTY. This ensures we traverse through
+			// the effects dependencies and correctly ensure each dependency is up-to-date.
+			if ((effect.f & CLEAN) !== 0 && effect.deps !== null) {
+				set_signal_status(effect, MAYBE_DIRTY);
+			}
+
+			if (is_dirty(effect)) {
+				update_effect(effect);
+			}
+
+			token.ran = false;
+		}
+	});
+}
+
+/**
+ * @param {() => void | (() => void)} fn
+ * @returns {Effect}
+ */
+export function async_effect(fn) {
+	return create_effect(ASYNC | EFFECT_PRESERVED, fn, true);
+}
+
+/**
+ * @param {() => void | (() => void)} fn
+ * @returns {Effect}
+ */
+export function render_effect(fn, flags = 0) {
+	return create_effect(RENDER_EFFECT | flags, fn, true);
+}
+
+/**
+ * @param {(...expressions: any) => void | (() => void)} fn
+ * @param {Array<() => any>} sync
+ * @param {Array<() => Promise<any>>} async
+ * @param {Blocker[]} blockers
+ */
+export function template_effect(fn, sync = [], async = [], blockers = []) {
+	flatten(blockers, sync, async, (values) => {
+		create_effect(RENDER_EFFECT, () => fn(...values.map(get)), true);
+	});
+}
+
+/**
+ * Like `template_effect`, but with an effect which is deferred until the batch commits
+ * @param {(...expressions: any) => void | (() => void)} fn
+ * @param {Array<() => any>} sync
+ * @param {Array<() => Promise<any>>} async
+ * @param {Blocker[]} blockers
+ */
+export function deferred_template_effect(fn, sync = [], async = [], blockers = []) {
+	if (async.length > 0 || blockers.length > 0) {
+		var decrement_pending = increment_pending();
+	}
+
+	flatten(blockers, sync, async, (values) => {
+		create_effect(EFFECT, () => fn(...values.map(get)), false);
+
+		if (decrement_pending) {
+			decrement_pending();
+		}
+	});
+}
+
+/**
+ * @param {(() => void)} fn
+ * @param {number} flags
+ */
+export function block(fn, flags = 0) {
+	var effect = create_effect(BLOCK_EFFECT | flags, fn, true);
+	if (DEV) {
+		effect.dev_stack = dev_stack;
+	}
+	return effect;
+}
+
+/**
+ * @param {(() => void)} fn
+ * @param {number} flags
+ */
+export function managed(fn, flags = 0) {
+	var effect = create_effect(MANAGED_EFFECT | flags, fn, true);
+	if (DEV) {
+		effect.dev_stack = dev_stack;
+	}
+	return effect;
+}
+
+/**
+ * @param {(() => void)} fn
+ */
+export function branch(fn) {
+	return create_effect(BRANCH_EFFECT | EFFECT_PRESERVED, fn, true);
+}
+
+/**
+ * @param {Effect} effect
+ */
+export function execute_effect_teardown(effect) {
+	var teardown = effect.teardown;
+	if (teardown !== null) {
+		const previously_destroying_effect = is_destroying_effect;
+		const previous_reaction = active_reaction;
+		set_is_destroying_effect(true);
+		set_active_reaction(null);
+		try {
+			teardown.call(null);
+		} finally {
+			set_is_destroying_effect(previously_destroying_effect);
+			set_active_reaction(previous_reaction);
+		}
+	}
+}
+
+/**
+ * @param {Effect} signal
+ * @param {boolean} remove_dom
+ * @returns {void}
+ */
+export function destroy_effect_children(signal, remove_dom = false) {
+	var effect = signal.first;
+	signal.first = signal.last = null;
+
+	while (effect !== null) {
+		const controller = effect.ac;
+
+		if (controller !== null) {
+			without_reactive_context(() => {
+				controller.abort(STALE_REACTION);
+			});
+		}
+
+		var next = effect.next;
+
+		if ((effect.f & ROOT_EFFECT) !== 0) {
+			// this is now an independent root
+			effect.parent = null;
+		} else {
+			destroy_effect(effect, remove_dom);
+		}
+
+		effect = next;
+	}
+}
+
+/**
+ * @param {Effect} signal
+ * @returns {void}
+ */
+export function destroy_block_effect_children(signal) {
+	var effect = signal.first;
+
+	while (effect !== null) {
+		var next = effect.next;
+		if ((effect.f & BRANCH_EFFECT) === 0) {
+			destroy_effect(effect);
+		}
+		effect = next;
+	}
+}
+
+/**
+ * @param {Effect} effect
+ * @param {boolean} [remove_dom]
+ * @returns {void}
+ */
+export function destroy_effect(effect, remove_dom = true) {
+	var removed = false;
+
+	if (
+		(remove_dom || (effect.f & HEAD_EFFECT) !== 0) &&
+		effect.nodes !== null &&
+		effect.nodes.end !== null
+	) {
+		remove_effect_dom(effect.nodes.start, /** @type {TemplateNode} */ (effect.nodes.end));
+		removed = true;
+	}
+
+	destroy_effect_children(effect, remove_dom && !removed);
+	remove_reactions(effect, 0);
+	set_signal_status(effect, DESTROYED);
+
+	var transitions = effect.nodes && effect.nodes.t;
+
+	if (transitions !== null) {
+		for (const transition of transitions) {
+			transition.stop();
+		}
+	}
+
+	execute_effect_teardown(effect);
+
+	var parent = effect.parent;
+
+	// If the parent doesn't have any children, then skip this work altogether
+	if (parent !== null && parent.first !== null) {
+		unlink_effect(effect);
+	}
+
+	if (DEV) {
+		effect.component_function = null;
+	}
+
+	// `first` and `child` are nulled out in destroy_effect_children
+	// we don't null out `parent` so that error propagation can work correctly
+	effect.next =
+		effect.prev =
+		effect.teardown =
+		effect.ctx =
+		effect.deps =
+		effect.fn =
+		effect.nodes =
+		effect.ac =
+			null;
+}
+
+/**
+ *
+ * @param {TemplateNode | null} node
+ * @param {TemplateNode} end
+ */
+export function remove_effect_dom(node, end) {
+	while (node !== null) {
+		/** @type {TemplateNode | null} */
+		var next = node === end ? null : get_next_sibling(node);
+
+		node.remove();
+		node = next;
+	}
+}
+
+/**
+ * Detach an effect from the effect tree, freeing up memory and
+ * reducing the amount of work that happens on subsequent traversals
+ * @param {Effect} effect
+ */
+export function unlink_effect(effect) {
+	var parent = effect.parent;
+	var prev = effect.prev;
+	var next = effect.next;
+
+	if (prev !== null) prev.next = next;
+	if (next !== null) next.prev = prev;
+
+	if (parent !== null) {
+		if (parent.first === effect) parent.first = next;
+		if (parent.last === effect) parent.last = prev;
+	}
+}
+
+/**
+ * When a block effect is removed, we don't immediately destroy it or yank it
+ * out of the DOM, because it might have transitions. Instead, we 'pause' it.
+ * It stays around (in memory, and in the DOM) until outro transitions have
+ * completed, and if the state change is reversed then we _resume_ it.
+ * A paused effect does not update, and the DOM subtree becomes inert.
+ * @param {Effect} effect
+ * @param {() => void} [callback]
+ * @param {boolean} [destroy]
+ */
+export function pause_effect(effect, callback, destroy = true) {
+	/** @type {TransitionManager[]} */
+	var transitions = [];
+
+	pause_children(effect, transitions, true);
+
+	var fn = () => {
+		if (destroy) destroy_effect(effect);
+		if (callback) callback();
+	};
+
+	var remaining = transitions.length;
+	if (remaining > 0) {
+		var check = () => --remaining || fn();
+		for (var transition of transitions) {
+			transition.out(check);
+		}
+	} else {
+		fn();
+	}
+}
+
+/**
+ * @param {Effect} effect
+ * @param {TransitionManager[]} transitions
+ * @param {boolean} local
+ */
+function pause_children(effect, transitions, local) {
+	if ((effect.f & INERT) !== 0) return;
+	effect.f ^= INERT;
+
+	var t = effect.nodes && effect.nodes.t;
+
+	if (t !== null) {
+		for (const transition of t) {
+			if (transition.is_global || local) {
+				transitions.push(transition);
+			}
+		}
+	}
+
+	var child = effect.first;
+
+	while (child !== null) {
+		var sibling = child.next;
+		var transparent =
+			(child.f & EFFECT_TRANSPARENT) !== 0 ||
+			// If this is a branch effect without a block effect parent,
+			// it means the parent block effect was pruned. In that case,
+			// transparency information was transferred to the branch effect.
+			((child.f & BRANCH_EFFECT) !== 0 && (effect.f & BLOCK_EFFECT) !== 0);
+		// TODO we don't need to call pause_children recursively with a linked list in place
+		// it's slightly more involved though as we have to account for `transparent` changing
+		// through the tree.
+		pause_children(child, transitions, transparent ? local : false);
+		child = sibling;
+	}
+}
+
+/**
+ * The opposite of `pause_effect`. We call this if (for example)
+ * `x` becomes falsy then truthy: `{#if x}...{/if}`
+ * @param {Effect} effect
+ */
+export function resume_effect(effect) {
+	resume_children(effect, true);
+}
+
+/**
+ * @param {Effect} effect
+ * @param {boolean} local
+ */
+function resume_children(effect, local) {
+	if ((effect.f & INERT) === 0) return;
+	effect.f ^= INERT;
+
+	// If a dependency of this effect changed while it was paused,
+	// schedule the effect to update. we don't use `is_dirty`
+	// here because we don't want to eagerly recompute a derived like
+	// `{#if foo}{foo.bar()}{/if}` if `foo` is now `undefined
+	if ((effect.f & CLEAN) === 0) {
+		set_signal_status(effect, DIRTY);
+		schedule_effect(effect);
+	}
+
+	var child = effect.first;
+
+	while (child !== null) {
+		var sibling = child.next;
+		var transparent = (child.f & EFFECT_TRANSPARENT) !== 0 || (child.f & BRANCH_EFFECT) !== 0;
+		// TODO we don't need to call resume_children recursively with a linked list in place
+		// it's slightly more involved though as we have to account for `transparent` changing
+		// through the tree.
+		resume_children(child, transparent ? local : false);
+		child = sibling;
+	}
+
+	var t = effect.nodes && effect.nodes.t;
+
+	if (t !== null) {
+		for (const transition of t) {
+			if (transition.is_global || local) {
+				transition.in();
+			}
+		}
+	}
+}
+
+export function aborted(effect = /** @type {Effect} */ (active_effect)) {
+	return (effect.f & DESTROYED) !== 0;
+}
+
+/**
+ * @param {Effect} effect
+ * @param {DocumentFragment} fragment
+ */
+export function move_effect(effect, fragment) {
+	if (!effect.nodes) return;
+
+	/** @type {TemplateNode | null} */
+	var node = effect.nodes.start;
+	var end = effect.nodes.end;
+
+	while (node !== null) {
+		/** @type {TemplateNode | null} */
+		var next = node === end ? null : get_next_sibling(node);
+
+		fragment.append(node);
+		node = next;
+	}
+}