Feat: Add Box

packages/runed/src/lib/utilities/box/box.svelte.test.ts

@@ -0,0 +1,113 @@
+import { box, ref } from "./box.svelte.js";
+
+describe("box", () => {
+	it("updates when the referenced value updates", () => {
+		let count = $state(0);
+		const boxed = box(() => count);
+		expect(boxed.current).toBe(0);
+
+		count = 1;
+		expect(boxed.current).toBe(1);
+	});
+
+	it("creates a readonly box when only a getter is passed", () => {
+		const boxed = box(() => 0);
+
+		function set() {
+			// @ts-expect-error It's readonly
+			boxed.current = 1;
+		}
+
+		expect(set).toThrowError();
+	});
+
+	it("creates a writable box when a getter and setter are passed", () => {
+		let count = $state(0);
+		const boxed = box(
+			() => count,
+			(value) => {
+				count = value;
+			}
+		);
+		expect(boxed.current).toBe(0);
+
+		boxed.current = 1;
+		expect(boxed.current).toBe(1);
+		expect(count).toBe(1);
+
+		count = 2;
+		expect(boxed.current).toBe(2);
+	});
+
+	it("memoizes the getter", () => {
+		let count = $state(0);
+		const fn = vi.fn(() => count);
+		const boxed = box(fn);
+		expect(fn).not.toHaveBeenCalled();
+
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(1);
+
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(1);
+
+		count = 1;
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(2);
+
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(2);
+	});
+});
+
+describe("ref", () => {
+	it("updates when the referenced value updates", () => {
+		let count = 0;
+		const boxed = ref(() => count);
+		expect(boxed.current).toBe(0);
+
+		count = 1;
+		expect(boxed.current).toBe(1);
+	});
+
+	it("creates a readonly box when only a getter is passed", () => {
+		const boxed = ref(() => 0);
+
+		function set() {
+			// @ts-expect-error It's readonly
+			boxed.current = 1;
+		}
+
+		expect(set).toThrowError();
+	});
+
+	it("creates a writable box when a getter and setter are passed", () => {
+		let count = 0;
+		const boxed = ref(
+			() => count,
+			(value) => {
+				count = value;
+			}
+		);
+		expect(boxed.current).toBe(0);
+
+		boxed.current = 1;
+		expect(boxed.current).toBe(1);
+		expect(count).toBe(1);
+
+		count = 2;
+		expect(boxed.current).toBe(2);
+	});
+
+	it("does not memoize the getter", () => {
+		const fn = vi.fn(() => 0);
+		const boxed = ref(fn);
+		expect(fn).not.toHaveBeenCalled();
+
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(1);
+
+		boxed.current;
+		expect(fn).toHaveBeenCalledTimes(2);
+	});
+});

packages/runed/src/lib/utilities/box/box.svelte.ts

@@ -0,0 +1,61 @@
+import type { Getter, Setter } from "$lib/internal/types.js";
+
+export type Box<T> = {
+	readonly current: T;
+	readonly get: Getter<T>;
+};
+
+export type WritableBox<T> = {
+	current: T;
+	readonly get: Getter<T>;
+	readonly set: Setter<T>;
+};
+
+export function box<T>(get: Getter<T>): Box<T>;
+export function box<T>(get: Getter<T>, set: Setter<T>): WritableBox<T>;
+export function box<T>(get: Getter<T>, set?: Setter<T>): Box<T> {
+	const current = $derived.by(get);
+	if (set !== undefined) {
+		return new WritableRef(() => current, set);
+	}
+	return new Ref(() => current);
+}
+
+export function ref<T>(get: Getter<T>): Box<T>;
+export function ref<T>(get: Getter<T>, set: Setter<T>): WritableBox<T>;
+export function ref<T>(get: Getter<T>, set?: Setter<T>): Box<T> {
+	if (set !== undefined) {
+		return new WritableRef(get, set);
+	}
+	return new Ref(get);
+}
+
+class Ref<T> {
+	readonly get: Getter<T>;
+
+	constructor(get: Getter<T>) {
+		this.get = get;
+	}
+
+	get current(): T {
+		return this.get();
+	}
+}
+
+class WritableRef<T> {
+	readonly get: Getter<T>;
+	readonly set: Setter<T>;
+
+	constructor(get: Getter<T>, set: Setter<T>) {
+		this.get = get;
+		this.set = set;
+	}
+
+	get current(): T {
+		return this.get();
+	}
+
+	set current(value: T) {
+		this.set(value);
+	}
+}

packages/runed/src/lib/utilities/box/index.ts

@@ -0,0 +1 @@
+export * from "./box.svelte.js";