vigla 0.0.0 → 0.2.0

package/src/runtime/reactivity/errors.ts

@@ -0,0 +1,73 @@
+import { failure, warn } from '../../shared/diagnostics.ts';
+
+function fail(code: string, message: string): never {
+	throw failure(code, message);
+}
+
+export function orphan(rune: string): never {
+	return fail(
+		'effect_orphan',
+		`\`${rune}\` can only be used inside an effect (e.g. during component initialisation)`
+	);
+}
+
+export function teardownOrphan(): never {
+	return fail('teardown_without_owner', '`onDestroy` can only be used where an owner exists');
+}
+
+export function asyncOrphan(): never {
+	return fail(
+		'async_derived_orphan',
+		'Cannot create a `$derived(...)` with an `await` expression outside of an effect tree'
+	);
+}
+
+export function referencesSelf(): never {
+	return fail('derived_references_self', 'A derived value cannot reference itself recursively');
+}
+
+export function pendingOutside(): never {
+	return fail(
+		'effect_pending_outside_reaction',
+		'`$effect.pending()` can only be called inside an effect or derived'
+	);
+}
+
+export function forkDiscarded(): never {
+	return fail('fork_discarded', 'Cannot commit a fork that was already discarded');
+}
+
+export function forkTiming(): never {
+	return fail(
+		'fork_timing',
+		'Cannot create a fork inside an effect or when state changes are pending'
+	);
+}
+
+export function unsafeMutation(): never {
+	return fail(
+		'state_unsafe_mutation',
+		'Updating state inside `$derived(...)`, `$inspect(...)` or a template expression is forbidden. If the value should not be reactive, declare it without `$state`'
+	);
+}
+
+export function descriptorsFixed(): never {
+	return fail(
+		'state_descriptors_fixed',
+		'Property descriptors defined on `$state` objects must contain `value` and always be `enumerable`, `configurable` and `writable`.'
+	);
+}
+
+export function depthExceeded(): Error {
+	return failure(
+		'effect_update_depth_exceeded',
+		'Maximum update depth exceeded. This typically indicates that an effect reads and writes the same piece of state'
+	);
+}
+
+export function inertDerived(): void {
+	warn(
+		'derived_inert',
+		'Reading a derived belonging to a now-destroyed effect may result in stale values'
+	);
+}

package/src/runtime/reactivity/external.ts

@@ -0,0 +1,56 @@
+import { DEV } from 'esm-env';
+import {
+	Connection,
+	type Connected,
+	type Subscribable,
+	type WritableSource
+} from '../../shared/external.ts';
+import { write } from './scheduler.ts';
+import { sequence } from './history.ts';
+import { teardown } from './effects.ts';
+import { mutableSource } from './sources.ts';
+import { tag } from './provenance.ts';
+import { get } from './reads.ts';
+import { untrack } from './tracking.ts';
+
+export function external<T>(
+	read: () => Subscribable<T> | null | undefined,
+	name = 'source',
+	label = name
+): Connected<T> {
+	const value = mutableSource<T>(undefined as T);
+	if (DEV) tag(value, label);
+	const connection = new Connection<T>((_before, next) => {
+		write(value, next, sequence());
+	});
+	teardown(() => connection.dispose());
+	const current = (): T => {
+		const input = read();
+		untrack(() => connection.select(input, name));
+		value.v = connection.value;
+		return get(value);
+	};
+	const set = (value: T): void => (read() as WritableSource<T>).set(value);
+	return {
+		get current() {
+			return current();
+		},
+		set current(value: T) {
+			set(value);
+		},
+		get peek() {
+			return untrack(current);
+		},
+		mutate(result) {
+			set(untrack(current));
+			return result;
+		},
+		refresh(result) {
+			connection.refresh(untrack(read));
+			return result;
+		},
+		dispose() {
+			connection.dispose();
+		}
+	};
+}

package/src/runtime/reactivity/fork.ts

@@ -0,0 +1,60 @@
+import { createBatch, open, processing, untouched, within } from './batch.ts';
+import { apply, flushSync, process } from './scheduler.ts';
+import { inside } from './views.ts';
+import { destroy, teardown } from './effects.ts';
+import { forkDiscarded, forkTiming } from './errors.ts';
+import { application, type Effect } from './graph.ts';
+import { adopt, discard, waitFor } from './held.ts';
+import { owner } from './tracking.ts';
+
+export interface Fork {
+	commit(): Promise<void>;
+	discard(): void;
+}
+
+function admits(caller: Effect | null): boolean {
+	if (processing !== null) return false;
+	if (open === null) return true;
+	if (caller === null) return false;
+	const mine = application(caller);
+	for (const effect of open.queued) if (application(effect) === mine) return false;
+	return true;
+}
+
+export function fork(fn: () => void): Fork {
+	const holder = owner;
+	if (!admits(holder)) forkTiming();
+	flushSync();
+	const batch = createBatch();
+	batch.fork = true;
+	batch.after = new Map();
+	adopt(batch);
+	inside(batch, fn);
+	process(batch);
+	untouched(batch);
+	const committed = waitFor(batch);
+	let committing = false;
+	if (holder !== null && holder.destroyed) discard(batch);
+	else if (holder !== null && !batch.done) {
+		const ending = teardown(() => {
+			if (!committing) discard(batch);
+		});
+		void committed.then(() => destroy(ending));
+	}
+	return {
+		async commit() {
+			if (!committing) {
+				if (batch.done) forkDiscarded();
+				committing = true;
+				adopt(batch);
+				batch.fork = false;
+				within(batch, () => apply(batch));
+				flushSync();
+			}
+			await committed;
+		},
+		discard() {
+			if (!committing) discard(batch);
+		}
+	};
+}

package/src/runtime/reactivity/front.ts

@@ -0,0 +1,20 @@
+import { locateFront } from '../../shared/diagnostics.ts';
+import type { Format } from '../../shared/format.ts';
+import { ambient } from './carried.ts';
+import type { Effect } from './graph.ts';
+
+const fronts = new WeakMap<Effect, Format>();
+
+export function setFront(tree: Effect, front: Format): void {
+	fronts.set(tree, front);
+}
+
+export function frontOf(effect: Effect | null): Format | null {
+	for (let at = effect; at !== null; at = at.parent) {
+		const front = fronts.get(at);
+		if (front !== undefined) return front;
+	}
+	return null;
+}
+
+locateFront(() => frontOf(ambient()));

package/src/runtime/reactivity/graph.ts

@@ -0,0 +1,129 @@
+export const CLEAN = 0;
+export const MAYBE = 1;
+export const DIRTY = 2;
+
+export const ROOT = 1;
+export const BRANCH = 2;
+export const BLOCK = 3;
+export const TEMPLATE = 4;
+export const EFFECT = 5;
+export const EAGER = 6;
+
+export const SOURCE = 0;
+export const DERIVED = 7;
+
+export type Kind =
+	| typeof ROOT
+	| typeof BRANCH
+	| typeof BLOCK
+	| typeof TEMPLATE
+	| typeof EFFECT
+	| typeof EAGER;
+
+export type Status = typeof CLEAN | typeof MAYBE | typeof DIRTY;
+
+export interface Source<T = unknown> {
+	equals?(before: T, after: T): boolean;
+	readonly kind: typeof SOURCE | typeof DERIVED;
+	v: T;
+	wv: number;
+	reactions: Reaction[] | null;
+	logged: number;
+	slot: number;
+	read: number;
+	links: number[] | null;
+}
+
+export interface Captured {
+	readonly values: ReadonlyMap<Source, unknown>;
+	readonly viewed: boolean;
+}
+
+export interface Reaction {
+	status: Status;
+	deps: Source[] | null;
+	rv: number;
+	slots: number[] | null;
+	captured: Captured | null;
+}
+
+export interface Failure {
+	readonly error: unknown;
+}
+
+const retaining = new WeakSet<Derived>();
+
+export function retainFailures(derived: Derived): void {
+	retaining.add(derived);
+}
+
+export function retainsFailures(derived: Derived): boolean {
+	return retaining.has(derived);
+}
+
+export interface Derived<T = unknown> extends Source<T>, Reaction {
+	readonly kind: typeof DERIVED;
+	readonly fn: () => T;
+	readonly owner: Effect | null;
+	effects: Effect[] | null;
+	frozen: Effect[] | null;
+	failure: Failure | null;
+	computed: boolean;
+	lapses: boolean;
+}
+
+export interface Boundary {
+	readonly parent: Boundary | null;
+	readonly showing: boolean;
+	settle(delta: 1 | -1): void;
+	failed(error: unknown): void;
+}
+
+export interface Effect extends Reaction {
+	readonly kind: Kind;
+	boundary: Boundary | null;
+	fn: (() => void | (() => void)) | null;
+	teardown: (() => void) | null;
+	parent: Effect | null;
+	first: Effect | null;
+	last: Effect | null;
+	prev: Effect | null;
+	next: Effect | null;
+	owned: Derived[] | null;
+	units: Set<() => void> | null;
+	context: unknown;
+	order: number;
+	batch: number;
+	forked: boolean;
+	async: boolean;
+	running: boolean;
+	destroyed: boolean;
+	inert: boolean;
+	pending: boolean;
+	scope: boolean;
+	preserved: boolean;
+}
+
+let clock = 0;
+
+export function equal<T>(source: Source<T>, before: T, after: T): boolean {
+	return source.equals === undefined ? Object.is(before, after) : source.equals(before, after);
+}
+
+export function stamp(): number {
+	return ++clock;
+}
+
+export function now(): number {
+	return clock;
+}
+
+export function isDerived(node: Source | Reaction): node is Derived {
+	return (node as Source | Effect).kind === DERIVED;
+}
+
+export function application(effect: Effect): Effect {
+	let top = effect;
+	while (top.parent !== null) top = top.parent;
+	return top;
+}

package/src/runtime/reactivity/handlers.ts

@@ -0,0 +1,55 @@
+import type { Boundary, Effect } from './graph.ts';
+import { setOwner, withoutReaction } from './tracking.ts';
+
+type ErrorHandler = (error: unknown) => void;
+
+const boundaries = new WeakMap<Effect, FailureBoundary>();
+
+class FailureBoundary implements Boundary {
+	readonly showing = false;
+	readonly handlers: ErrorHandler[] = [];
+	readonly #effect: Effect;
+
+	constructor(effect: Effect) {
+		this.#effect = effect;
+	}
+
+	get parent(): Boundary | null {
+		return this.#effect.parent?.boundary ?? null;
+	}
+
+	settle(delta: 1 | -1): void {
+		this.parent?.settle(delta);
+	}
+
+	failed(error: unknown): void {
+		const handler = this.handlers.at(-1);
+		if (handler === undefined || this.#effect.destroyed) throw error;
+		const previous = setOwner(this.#effect);
+		try {
+			withoutReaction(() => handler(error));
+		} finally {
+			setOwner(previous);
+		}
+	}
+}
+
+export function handlerOf(effect: Effect): Boundary | null {
+	const boundary = boundaries.get(effect);
+	return effect.destroyed || boundary?.handlers.length === 0 ? null : (boundary ?? null);
+}
+
+export function handle(effect: Effect, handler: ErrorHandler): () => void {
+	let boundary = boundaries.get(effect);
+	if (boundary === undefined) {
+		boundary = new FailureBoundary(effect);
+		boundaries.set(effect, boundary);
+	}
+	const handlers = boundary.handlers;
+	const registered: ErrorHandler = (error) => handler(error);
+	handlers.push(registered);
+	return () => {
+		const index = handlers.indexOf(registered);
+		if (index !== -1) handlers.splice(index, 1);
+	};
+}