@zeix/cause-effect 0.18.2 → 0.18.3

package/src/nodes/slot.ts

@@ -0,0 +1,134 @@
+import { ReadonlySignalError, validateSignalValue } from '../errors'
+import {
+	activeSink,
+	batchDepth,
+	DEFAULT_EQUALITY,
+	FLAG_DIRTY,
+	flush,
+	link,
+	type MemoNode,
+	propagate,
+	refresh,
+	type Signal,
+	type SignalOptions,
+	type SinkNode,
+	TYPE_SLOT,
+} from '../graph'
+import { isMutableSignal, isSignal } from '../signal'
+import { isObjectOfType } from '../util'
+
+/* === Types === */
+
+/**
+ * A signal that delegates its value to a swappable backing signal.
+ *
+ * Slots provide a stable reactive source at a fixed position (e.g. an object property)
+ * while allowing the backing signal to be replaced without breaking subscribers.
+ * The object shape is compatible with `Object.defineProperty()` descriptors:
+ * `get`, `set`, `configurable`, and `enumerable` are used by the property definition;
+ * `replace()` and `current()` are kept on the slot object for integration-layer control.
+ *
+ * @template T - The type of value held by the delegated signal.
+ */
+type Slot<T extends {}> = {
+	readonly [Symbol.toStringTag]: 'Slot'
+	/** Descriptor field: allows the property to be redefined or deleted. */
+	configurable: true
+	/** Descriptor field: the property shows up during enumeration. */
+	enumerable: true
+	/** Reads the current value from the delegated signal, tracking dependencies. */
+	get(): T
+	/** Writes a value to the delegated signal. Throws `ReadonlySignalError` if the delegated signal is read-only. */
+	set(next: T): void
+	/** Swaps the backing signal, invalidating all downstream subscribers. Narrowing (`U extends T`) is allowed. */
+	replace<U extends T>(next: Signal<U>): void
+	/** Returns the currently delegated signal. */
+	current(): Signal<T>
+}
+
+/* === Exported Functions === */
+
+/**
+ * Creates a slot signal that delegates its value to a swappable backing signal.
+ *
+ * A slot acts as a stable reactive source that can be used as a property descriptor
+ * via `Object.defineProperty(target, key, slot)`. Subscribers link to the slot itself,
+ * so replacing the backing signal with `replace()` invalidates them without breaking
+ * existing edges. Setter calls forward to the current backing signal when it is writable.
+ *
+ * @since 0.18.3
+ * @template T - The type of value held by the delegated signal.
+ * @param initialSignal - The initial signal to delegate to.
+ * @param options - Optional configuration for the slot.
+ * @param options.equals - Custom equality function. Defaults to strict equality (`===`).
+ * @param options.guard - Type guard to validate values passed to `set()`.
+ * @returns A `Slot<T>` object usable both as a property descriptor and as a reactive signal.
+ */
+function createSlot<T extends {}>(
+	initialSignal: Signal<T>,
+	options?: SignalOptions<T>,
+): Slot<T> {
+	validateSignalValue(TYPE_SLOT, initialSignal, isSignal)
+
+	let delegated = initialSignal as Signal<T>
+	const guard = options?.guard
+
+	const node: MemoNode<T> = {
+		fn: () => delegated.get(),
+		value: undefined as unknown as T,
+		flags: FLAG_DIRTY,
+		sources: null,
+		sourcesTail: null,
+		sinks: null,
+		sinksTail: null,
+		equals: options?.equals ?? DEFAULT_EQUALITY,
+		error: undefined,
+	}
+
+	const get = (): T => {
+		if (activeSink) link(node, activeSink)
+		refresh(node as unknown as SinkNode)
+		if (node.error) throw node.error
+		return node.value
+	}
+
+	const set = (next: T): void => {
+		if (!isMutableSignal(delegated))
+			throw new ReadonlySignalError(TYPE_SLOT)
+		validateSignalValue(TYPE_SLOT, next, guard)
+
+		delegated.set(next)
+	}
+
+	const replace = <U extends T>(next: Signal<U>): void => {
+		validateSignalValue(TYPE_SLOT, next, isSignal)
+
+		delegated = next
+		node.flags |= FLAG_DIRTY
+		for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+		if (batchDepth === 0) flush()
+	}
+
+	return {
+		[Symbol.toStringTag]: TYPE_SLOT,
+		configurable: true,
+		enumerable: true,
+		get,
+		set,
+		replace,
+		current: () => delegated,
+	}
+}
+
+/**
+ * Checks if a value is a Slot signal.
+ *
+ * @since 0.18.3
+ * @param value - The value to check
+ * @returns True if the value is a Slot
+ */
+function isSlot<T extends {} = unknown & {}>(value: unknown): value is Slot<T> {
+	return isObjectOfType(value, TYPE_SLOT)
+}
+
+export { createSlot, isSlot, type Slot }

package/src/signal.ts

@@ -8,6 +8,7 @@ import {
 	TYPE_LIST,
 	TYPE_MEMO,
 	TYPE_SENSOR,
+	TYPE_SLOT,
 	TYPE_STATE,
 	TYPE_STORE,
 	TYPE_TASK,
@@ -122,6 +123,7 @@ function isSignal<T extends {}>(value: unknown): value is Signal<T> {
 		TYPE_MEMO,
 		TYPE_TASK,
 		TYPE_SENSOR,
+		TYPE_SLOT,
 		TYPE_LIST,
 		TYPE_COLLECTION,
 		TYPE_STORE,

package/test/effect.test.ts

@@ -249,6 +249,23 @@ describe('match', () => {
 		}
 	})
 
+	test('should preserve tuple types in ok handler', () => {
+		const a = createState(1)
+		const b = createState('hello')
+		createEffect(() =>
+			match([a, b], {
+				ok: ([aVal, bVal]) => {
+					// If tuple types are preserved, aVal is number and bVal is string
+					// If widened, both would be string | number
+					const num: number = aVal
+					const str: string = bVal
+					expect(num).toBe(1)
+					expect(str).toBe('hello')
+				},
+			}),
+		)
+	})
+
 	test('should throw RequiredOwnerError when called outside an owner', () => {
 		expect(() => match([], { ok: () => {} })).toThrow(RequiredOwnerError)
 	})

package/test/signal.test.ts

@@ -6,6 +6,7 @@ import {
 	createMutableSignal,
 	createScope,
 	createSignal,
+	createSlot,
 	createState,
 	createStore,
 	createTask,
@@ -229,6 +230,7 @@ describe('isSignal', () => {
 			expect(isSignal(createTask(async () => 42))).toBe(true)
 			expect(isSignal(createStore({ a: 1 }))).toBe(true)
 			expect(isSignal(createList([1, 2, 3]))).toBe(true)
+			expect(isSignal(createSlot(createState(1)))).toBe(true)
 		})
 		cleanup()
 	})

package/test/slot.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	batch,
+	createEffect,
+	createMemo,
+	createSlot,
+	createState,
+} from '../index.ts'
+import { InvalidSignalValueError, NullishSignalValueError } from '../src/errors'
+
+describe('Slot', () => {
+	test('should replace delegated signal and re-subscribe sinks', () => {
+		const local = createState(1)
+		const parent = createState(10)
+		const derived = createMemo(() => parent.get())
+		const slot = createSlot(local)
+
+		const target = {}
+		Object.defineProperty(target, 'value', slot)
+
+		let runs = 0
+		let seen = 0
+		createEffect(() => {
+			seen = (target as { value: number }).value
+			runs++
+		})
+
+		expect(runs).toBe(1)
+		expect(seen).toBe(1)
+
+		slot.replace(derived)
+		expect(runs).toBe(2)
+		expect(seen).toBe(10)
+
+		// Old delegated signal should no longer trigger downstream sinks
+		local.set(2)
+		expect(runs).toBe(2)
+
+		parent.set(11)
+		expect(runs).toBe(3)
+		expect(seen).toBe(11)
+	})
+
+	test('should forward property set to writable delegated signal', () => {
+		const source = createState(2)
+		const slot = createSlot(source)
+		const target = {}
+		Object.defineProperty(target, 'value', slot)
+		;(target as { value: number }).value = 3
+
+		expect(source.get()).toBe(3)
+		expect((target as { value: number }).value).toBe(3)
+	})
+
+	test('should throw on set when delegated signal is read-only', () => {
+		const source = createState(2)
+		const readonly = createMemo(() => source.get() * 2)
+		const slot = createSlot(source)
+		const target = {}
+		Object.defineProperty(target, 'value', slot)
+		slot.replace(readonly)
+
+		expect(() => {
+			;(target as { value: number }).value = 7
+		}).toThrow('[Slot] Signal is read-only')
+	})
+
+	test('should keep replace handle outside property descriptor', () => {
+		const source = createState(1)
+		const slot = createSlot(source)
+		const target = {}
+		Object.defineProperty(target, 'value', slot)
+
+		const descriptor = Object.getOwnPropertyDescriptor(target, 'value')
+		expect(descriptor).toBeDefined()
+		expect(typeof descriptor?.get).toBe('function')
+		expect(typeof descriptor?.set).toBe('function')
+		expect((descriptor as unknown as { replace?: unknown }).replace).toBe(
+			undefined,
+		)
+		expect(typeof slot.replace).toBe('function')
+	})
+
+	test('should batch multiple replacements into one downstream rerun', () => {
+		const a = createState(1)
+		const b = createState(2)
+		const c = createState(3)
+		const slot = createSlot(a)
+		const target = {}
+		Object.defineProperty(target, 'value', slot)
+
+		let runs = 0
+		createEffect(() => {
+			void (target as { value: number }).value
+			runs++
+		})
+		expect(runs).toBe(1)
+
+		batch(() => {
+			slot.replace(b)
+			slot.replace(c)
+		})
+		expect(runs).toBe(2)
+	})
+
+	test('should validate initial signal and replacement signal', () => {
+		expect(() => {
+			// @ts-expect-error: deliberate error test
+			createSlot(null)
+		}).toThrow(NullishSignalValueError)
+
+		const slot = createSlot(createState(1))
+		expect(() => {
+			// @ts-expect-error: deliberate error test
+			slot.replace(42)
+		}).toThrow(InvalidSignalValueError)
+	})
+})

package/types/index.d.ts

@@ -1,15 +1,16 @@
 /**
  * @name Cause & Effect
- * @version 0.18.1
+ * @version 0.18.3
  * @author Esther Brunner
  */
-export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
+export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';
 export { batch, type Cleanup, type ComputedOptions, createScope, type EffectCallback, type MaybeCleanup, type MemoCallback, type Signal, type SignalOptions, SKIP_EQUALITY, type TaskCallback, untrack, } from './src/graph';
 export { type Collection, type CollectionCallback, type CollectionChanges, type CollectionOptions, createCollection, type DeriveCollectionCallback, isCollection, } from './src/nodes/collection';
 export { createEffect, type MatchHandlers, type MaybePromise, match, } from './src/nodes/effect';
 export { createList, isEqual, isList, type KeyConfig, type List, type ListOptions, } from './src/nodes/list';
 export { createMemo, isMemo, type Memo } from './src/nodes/memo';
 export { createSensor, isSensor, type Sensor, type SensorCallback, type SensorOptions, } from './src/nodes/sensor';
+export { createSlot, isSlot, type Slot } from './src/nodes/slot';
 export { createState, isState, type State, type UpdateCallback, } from './src/nodes/state';
 export { createStore, isStore, type Store, type StoreOptions, } from './src/nodes/store';
 export { createTask, isTask, type Task } from './src/nodes/task';

package/types/src/errors.d.ts

@@ -64,6 +64,14 @@ declare class InvalidCallbackError extends TypeError {
      */
     constructor(where: string, value: unknown);
 }
+declare class ReadonlySignalError extends Error {
+    /**
+     * Constructs a new ReadonlySignalError.
+     *
+     * @param where - The location where the error occurred.
+     */
+    constructor(where: string);
+}
 /**
  * Error thrown when an API requiring an owner is called without one.
  */
@@ -82,4 +90,4 @@ declare function validateSignalValue<T extends {}>(where: string, value: unknown
 declare function validateReadValue<T extends {}>(where: string, value: T | null | undefined): asserts value is T;
 declare function validateCallback(where: string, value: unknown): asserts value is (...args: unknown[]) => unknown;
 declare function validateCallback<T>(where: string, value: unknown, guard: (value: unknown) => value is T): asserts value is T;
-export { type Guard, CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, UnsetSignalValueError, InvalidCallbackError, RequiredOwnerError, DuplicateKeyError, validateSignalValue, validateReadValue, validateCallback, };
+export { type Guard, CircularDependencyError, NullishSignalValueError, InvalidSignalValueError, UnsetSignalValueError, InvalidCallbackError, ReadonlySignalError, RequiredOwnerError, DuplicateKeyError, validateSignalValue, validateReadValue, validateCallback, };

package/types/src/graph.d.ts

@@ -117,8 +117,10 @@ declare const TYPE_SENSOR = "Sensor";
 declare const TYPE_LIST = "List";
 declare const TYPE_COLLECTION = "Collection";
 declare const TYPE_STORE = "Store";
+declare const TYPE_SLOT = "Slot";
 declare const FLAG_CLEAN = 0;
 declare const FLAG_DIRTY: number;
+declare const FLAG_RELINK: number;
 declare let activeSink: SinkNode | null;
 declare let activeOwner: OwnerNode | null;
 declare let batchDepth: number;
@@ -215,4 +217,4 @@ declare function untrack<T>(fn: () => T): T;
  * ```
  */
 declare function createScope(fn: () => MaybeCleanup): Cleanup;
-export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_STORE, TYPE_TASK, unlink, untrack, };
+export { type Cleanup, type ComputedOptions, type EffectCallback, type EffectNode, type MaybeCleanup, type MemoCallback, type MemoNode, type Scope, type Signal, type SignalOptions, type SinkNode, type StateNode, type TaskCallback, type TaskNode, activeOwner, activeSink, batch, batchDepth, createScope, DEFAULT_EQUALITY, SKIP_EQUALITY, FLAG_CLEAN, FLAG_DIRTY, FLAG_RELINK, flush, link, propagate, refresh, registerCleanup, runCleanup, runEffect, setState, trimSources, TYPE_COLLECTION, TYPE_LIST, TYPE_MEMO, TYPE_SENSOR, TYPE_STATE, TYPE_SLOT, TYPE_STORE, TYPE_TASK, unlink, untrack, };

package/types/src/nodes/effect.d.ts

@@ -1,6 +1,6 @@
 import { type Cleanup, type EffectCallback, type MaybeCleanup, type Signal } from '../graph';
 type MaybePromise<T> = T | Promise<T>;
-type MatchHandlers<T extends Signal<unknown & {}>[]> = {
+type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
     ok: (values: {
         [K in keyof T]: T[K] extends Signal<infer V> ? V : never;
     }) => MaybePromise<MaybeCleanup>;
@@ -44,5 +44,5 @@ declare function createEffect(fn: EffectCallback): Cleanup;
  * @since 0.15.0
  * @throws RequiredOwnerError If called without an active owner.
  */
-declare function match<T extends Signal<unknown & {}>[]>(signals: T, handlers: MatchHandlers<T>): MaybeCleanup;
+declare function match<T extends readonly Signal<unknown & {}>[]>(signals: readonly [...T], handlers: MatchHandlers<T>): MaybeCleanup;
 export { type MaybePromise, type MatchHandlers, createEffect, match };

package/types/src/nodes/slot.d.ts

@@ -0,0 +1,53 @@
+import { type Signal, type SignalOptions } from '../graph';
+/**
+ * A signal that delegates its value to a swappable backing signal.
+ *
+ * Slots provide a stable reactive source at a fixed position (e.g. an object property)
+ * while allowing the backing signal to be replaced without breaking subscribers.
+ * The object shape is compatible with `Object.defineProperty()` descriptors:
+ * `get`, `set`, `configurable`, and `enumerable` are used by the property definition;
+ * `replace()` and `current()` are kept on the slot object for integration-layer control.
+ *
+ * @template T - The type of value held by the delegated signal.
+ */
+type Slot<T extends {}> = {
+    readonly [Symbol.toStringTag]: 'Slot';
+    /** Descriptor field: allows the property to be redefined or deleted. */
+    configurable: true;
+    /** Descriptor field: the property shows up during enumeration. */
+    enumerable: true;
+    /** Reads the current value from the delegated signal, tracking dependencies. */
+    get(): T;
+    /** Writes a value to the delegated signal. Throws `ReadonlySignalError` if the delegated signal is read-only. */
+    set(next: T): void;
+    /** Swaps the backing signal, invalidating all downstream subscribers. Narrowing (`U extends T`) is allowed. */
+    replace<U extends T>(next: Signal<U>): void;
+    /** Returns the currently delegated signal. */
+    current(): Signal<T>;
+};
+/**
+ * Creates a slot signal that delegates its value to a swappable backing signal.
+ *
+ * A slot acts as a stable reactive source that can be used as a property descriptor
+ * via `Object.defineProperty(target, key, slot)`. Subscribers link to the slot itself,
+ * so replacing the backing signal with `replace()` invalidates them without breaking
+ * existing edges. Setter calls forward to the current backing signal when it is writable.
+ *
+ * @since 0.18.3
+ * @template T - The type of value held by the delegated signal.
+ * @param initialSignal - The initial signal to delegate to.
+ * @param options - Optional configuration for the slot.
+ * @param options.equals - Custom equality function. Defaults to strict equality (`===`).
+ * @param options.guard - Type guard to validate values passed to `set()`.
+ * @returns A `Slot<T>` object usable both as a property descriptor and as a reactive signal.
+ */
+declare function createSlot<T extends {}>(initialSignal: Signal<T>, options?: SignalOptions<T>): Slot<T>;
+/**
+ * Checks if a value is a Slot signal.
+ *
+ * @since 0.18.3
+ * @param value - The value to check
+ * @returns True if the value is a Slot
+ */
+declare function isSlot<T extends {} = unknown & {}>(value: unknown): value is Slot<T>;
+export { createSlot, isSlot, type Slot };