@zeix/cause-effect 1.0.0 → 1.0.2

package/src/nodes/list.ts

@@ -40,13 +40,33 @@ type DiffResult = {
 	remove: UnknownRecord
 }
 
+/**
+ * Key generation strategy for `createList` items.
+ * A string value is used as a prefix for auto-incremented keys (`prefix0`, `prefix1`, …).
+ * A function receives each item and returns a stable string key, or `undefined` to fall back to auto-increment.
+ *
+ * @template T - The type of items in the list
+ */
 type KeyConfig<T> = string | ((item: T) => string | undefined)
 
+/**
+ * Configuration options for `createList`.
+ *
+ * @template T - The type of items in the list
+ */
 type ListOptions<T extends {}> = {
+	/** Key generation strategy. A string prefix or a function `(item) => string | undefined`. Defaults to auto-increment. */
 	keyConfig?: KeyConfig<T>
+	/** Lifecycle callback invoked when the list gains its first downstream subscriber. Must return a cleanup function. */
 	watched?: () => Cleanup
 }
 
+/**
+ * A reactive ordered array with stable keys and per-item reactivity.
+ * Each item is a `State<T>` signal; structural changes (add/remove/sort) propagate reactively.
+ *
+ * @template T - The type of items in the list
+ */
 type List<T extends {}> = {
 	readonly [Symbol.toStringTag]: 'List'
 	readonly [Symbol.isConcatSpreadable]: true
@@ -62,6 +82,13 @@ type List<T extends {}> = {
 	indexOfKey(key: string): number
 	add(value: T): string
 	remove(keyOrIndex: string | number): void
+	/**
+	 * Updates an existing item by key, propagating to all subscribers.
+	 * No-op if the key does not exist or the value is reference-equal to the current value.
+	 * @param key - Stable key of the item to update
+	 * @param value - New value for the item
+	 */
+	replace(key: string, value: T): void
 	sort(compareFn?: (a: T, b: T) => number): void
 	splice(start: number, deleteCount?: number, ...items: T[]): T[]
 	deriveCollection<R extends {}>(
@@ -240,8 +267,9 @@ function diffArrays<T>(
  *
  * @since 0.18.0
  * @param value - Initial array of items
- * @param options - Optional configuration for key generation and watch lifecycle
- * @returns A List signal
+ * @param options.keyConfig - Key generation strategy: string prefix or `(item) => string | undefined`. Defaults to auto-increment.
+ * @param options.watched - Lifecycle callback invoked on first subscriber; must return a cleanup function called on last unsubscribe.
+ * @returns A `List` signal with reactive per-item `State` signals
  */
 function createList<T extends {}>(
 	value: T[],
@@ -474,6 +502,17 @@ function createList<T extends {}>(
 			}
 		},
 
+		replace(key: string, value: T) {
+			const signal = signals.get(key)
+			if (!signal) return
+			validateSignalValue(`${TYPE_LIST} item for key "${key}"`, value)
+			if (signal.get() === value) return
+			signal.set(value)
+			node.flags |= FLAG_DIRTY
+			for (let e = node.sinks; e; e = e.nextSink) propagate(e.sink)
+			if (batchDepth === 0) flush()
+		},
+
 		sort(compareFn?: (a: T, b: T) => number) {
 			const entries = keys
 				.map(key => [key, signals.get(key)?.get()] as [string, T])

package/src/nodes/memo.ts

@@ -36,7 +36,6 @@ type Memo<T extends {}> = {
 	 * Recomputes if dependencies have changed since last access.
 	 * When called inside another reactive context, creates a dependency.
 	 * @returns The computed value
-	 * @throws UnsetSignalValueError If the memo value is still unset when read.
 	 */
 	get(): T
 }

package/src/nodes/sensor.ts

@@ -35,11 +35,9 @@ type Sensor<T extends {}> = {
 }
 
 /**
- * A callback function for sensors when the sensor starts being watched.
+ * Configuration options for `createSensor`.
  *
- * @template T - The type of value observed
- * @param set - A function to set the observed value
- * @returns A cleanup function when the sensor stops being watched
+ * @template T - The type of value produced by the sensor
  */
 type SensorOptions<T extends {}> = SignalOptions<T> & {
 	/**
@@ -49,6 +47,14 @@ type SensorOptions<T extends {}> = SignalOptions<T> & {
 	value?: T
 }
 
+/**
+ * Setup callback for `createSensor`. Invoked when the sensor gains its first downstream
+ * subscriber; receives a `set` function to push new values into the graph.
+ *
+ * @template T - The type of value produced by the sensor
+ * @param set - Updates the sensor value and propagates the change to subscribers
+ * @returns A cleanup function invoked when the sensor loses all subscribers
+ */
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup
 
 /* === Exported Functions === */

package/src/nodes/store.ts

@@ -28,7 +28,11 @@ import { createState, type State } from './state'
 
 /* === Types === */
 
+/**
+ * Configuration options for `createStore`.
+ */
 type StoreOptions = {
+	/** Invoked when the store gains its first downstream subscriber; returns a cleanup called when the last one unsubscribes. */
 	watched?: () => Cleanup
 }
 
@@ -58,6 +62,13 @@ type BaseStore<T extends UnknownRecord> = {
 	remove(key: string): void
 }
 
+/**
+ * A reactive object with per-property reactivity.
+ * Each property is wrapped as a `State`, nested `Store`, or `List` signal, accessible directly via proxy.
+ * Updating one property only re-runs effects that read that property.
+ *
+ * @template T - The plain-object type whose properties become reactive signals
+ */
 type Store<T extends UnknownRecord> = BaseStore<T> & {
 	[K in keyof T]: T[K] extends readonly (infer U extends {})[]
 		? List<U>

package/src/signal.ts

@@ -22,6 +22,12 @@ import { isAsyncFunction, isFunction, isRecord, isUniformArray } from './util'
 
 /* === Types === */
 
+/**
+ * A readable and writable signal — the type union of `State`, `Store`, and `List`.
+ * Use as a parameter type for generic code that accepts any writable signal.
+ *
+ * @template T - The type of value held by the signal
+ */
 type MutableSignal<T extends {}> = {
 	get(): T
 	set(value: T): void

package/test/list.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import {
+	batch,
 	createEffect,
 	createList,
 	createMemo,
@@ -209,6 +210,126 @@ describe('List', () => {
 		})
 	})
 
+	describe('replace', () => {
+		test('should update the item signal value', () => {
+			const list = createList(['a', 'b', 'c'])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key = list.keyAt(1)!
+			list.replace(key, 'B')
+			expect(list.byKey(key)?.get()).toBe('B')
+		})
+
+		test('structural subscriber via keys() re-runs after replace(); byKey().set() does NOT', () => {
+			const list = createList(['x', 'y'])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key = list.keyAt(0)!
+			let effectCount = 0
+
+			// This effect subscribes structurally via keys() only — no list.get() call
+			createEffect(() => {
+				void [...list.keys()]
+				effectCount++
+			})
+
+			expect(effectCount).toBe(1)
+
+			// replace() propagates through node.sinks — structural subscriber re-runs
+			list.replace(key, 'X')
+			expect(effectCount).toBe(2)
+
+			// byKey().set() does NOT propagate through node.sinks — structural subscriber does NOT re-run
+			list.byKey(key)?.set('XX')
+			expect(effectCount).toBe(2)
+		})
+
+		test('direct subscriber via byKey().get() re-runs after replace()', () => {
+			const list = createList(['a', 'b'])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key = list.keyAt(0)!
+			let lastValue = ''
+			let effectCount = 0
+
+			createEffect(() => {
+				// biome-ignore lint/style/noNonNullAssertion: key is valid
+				lastValue = list.byKey(key)!.get()
+				effectCount++
+			})
+
+			expect(effectCount).toBe(1)
+			expect(lastValue).toBe('a')
+
+			list.replace(key, 'A')
+			expect(effectCount).toBe(2)
+			expect(lastValue).toBe('A')
+		})
+
+		test('no-op on equal value (same reference)', () => {
+			const obj = { id: 1 }
+			const list = createList([obj])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key = list.keyAt(0)!
+			let effectCount = 0
+
+			createEffect(() => {
+				list.get()
+				effectCount++
+			})
+
+			expect(effectCount).toBe(1)
+
+			list.replace(key, obj)
+			expect(effectCount).toBe(1)
+		})
+
+		test('no-op on missing key — does not throw and does not trigger effects', () => {
+			const list = createList([1, 2, 3])
+			let effectCount = 0
+
+			createEffect(() => {
+				list.get()
+				effectCount++
+			})
+
+			expect(effectCount).toBe(1)
+			expect(() => list.replace('nonexistent', 99)).not.toThrow()
+			expect(effectCount).toBe(1)
+		})
+
+		test('batch compatibility — effects run only once inside batch()', () => {
+			const list = createList(['a', 'b', 'c'])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key0 = list.keyAt(0)!
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key1 = list.keyAt(1)!
+			let effectCount = 0
+
+			createEffect(() => {
+				list.get()
+				effectCount++
+			})
+
+			expect(effectCount).toBe(1)
+
+			batch(() => {
+				list.replace(key0, 'A')
+				list.replace(key1, 'B')
+			})
+
+			expect(effectCount).toBe(2)
+			expect(list.get()).toEqual(['A', 'B', 'c'])
+		})
+
+		test('signal identity preserved — byKey() returns same signal before and after replace()', () => {
+			const list = createList([10, 20])
+			// biome-ignore lint/style/noNonNullAssertion: index is within bounds
+			const key = list.keyAt(0)!
+			const signalBefore = list.byKey(key)
+			list.replace(key, 99)
+			const signalAfter = list.byKey(key)
+			expect(signalBefore).toBe(signalAfter)
+		})
+	})
+
 	describe('sort', () => {
 		test('should sort with default string comparison', () => {
 			const list = createList([3, 1, 2])

package/tsconfig.json

@@ -12,6 +12,10 @@
 		"moduleResolution": "bundler",
 		"allowImportingTsExtensions": true,
 		"verbatimModuleSyntax": true,
+		"erasableSyntaxOnly": true,
+		"isolatedModules": true,
+		"resolveJsonModule": true,
+		"types": ["bun-types"],
 
 		// Editor-only mode - no emit
 		"noEmit": true,
@@ -24,11 +28,16 @@
 		"useUnknownInCatchVariables": true,
 		"noUncheckedSideEffectImports": true,
 		"noFallthroughCasesInSwitch": true,
+		"forceConsistentCasingInFileNames": true,
 
 		// Some stricter flags (disabled by default)
 		"noUnusedLocals": false,
 		"noUnusedParameters": false,
 		"noPropertyAccessFromIndexSignature": false,
+
+		/* Performance */
+		"incremental": true,
+		"tsBuildInfoFile": "./.tsbuildinfo",
 	},
 	"include": ["./**/*.ts"],
 	"exclude": ["node_modules", "types", "index.js"],

package/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * @name Cause & Effect
- * @version 1.0.0
+ * @version 1.0.2
  * @author Esther Brunner
  */
 export { CircularDependencyError, type Guard, InvalidCallbackError, InvalidSignalValueError, NullishSignalValueError, ReadonlySignalError, RequiredOwnerError, UnsetSignalValueError, } from './src/errors';

package/types/src/graph.d.ts

@@ -226,6 +226,8 @@ declare function createScope(fn: () => MaybeCleanup): Cleanup;
  * reactive graph.
  *
  * @since 0.18.5
+ * @param fn - The function to execute without an active owner
+ * @returns The return value of `fn`
  */
 declare function unown<T>(fn: () => T): T;
 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_CHECK, 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, unown, untrack, };

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

@@ -1,7 +1,21 @@
 import { type Cleanup, type Signal } from '../graph';
 import { type KeyConfig, type List } from './list';
 type CollectionSource<T extends {}> = List<T> | Collection<T>;
+/**
+ * Transformation callback for `deriveCollection` — sync or async.
+ * Sync callbacks produce a `Memo<T>` per item; async callbacks produce a `Task<T>`
+ * with automatic cancellation when the source item changes.
+ *
+ * @template T - The type of derived items
+ * @template U - The type of source items
+ */
 type DeriveCollectionCallback<T extends {}, U extends {}> = ((sourceValue: U) => T) | ((sourceValue: U, abort: AbortSignal) => Promise<T>);
+/**
+ * A read-only reactive keyed collection with per-item reactivity.
+ * Created by `createCollection` (externally driven) or via `.deriveCollection()` on a `List` or `Collection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type Collection<T extends {}> = {
     readonly [Symbol.toStringTag]: 'Collection';
     readonly [Symbol.isConcatSpreadable]: true;
@@ -16,16 +30,40 @@ type Collection<T extends {}> = {
     deriveCollection<R extends {}>(callback: (sourceValue: T, abort: AbortSignal) => Promise<R>): Collection<R>;
     readonly length: number;
 };
+/**
+ * Granular mutation descriptor passed to the `applyChanges` callback inside a `CollectionCallback`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionChanges<T> = {
+    /** Items to add. Each item is assigned a new key via the configured `keyConfig`. */
     add?: T[];
+    /** Items whose values have changed. Matched to existing entries by key. */
     change?: T[];
+    /** Items to remove. Matched to existing entries by key. */
     remove?: T[];
 };
+/**
+ * Configuration options for `createCollection`.
+ *
+ * @template T - The type of items in the collection
+ */
 type CollectionOptions<T extends {}> = {
+    /** Initial items. Defaults to `[]`. */
     value?: T[];
+    /** Key generation strategy. See `KeyConfig`. Defaults to auto-increment. */
     keyConfig?: KeyConfig<T>;
+    /** Factory for per-item signals. Defaults to `createState`. */
     createItem?: (value: T) => Signal<T>;
 };
+/**
+ * Setup callback for `createCollection`. Invoked when the collection gains its first downstream
+ * subscriber; receives an `applyChanges` function to push granular mutations into the graph.
+ *
+ * @template T - The type of items in the collection
+ * @param apply - Call with a `CollectionChanges` object to add, update, or remove items
+ * @returns A cleanup function invoked when the collection loses all subscribers
+ */
 type CollectionCallback<T extends {}> = (apply: (changes: CollectionChanges<T>) => void) => Cleanup;
 /**
  * Creates a derived Collection from a List or another Collection with item-level memoization.

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

@@ -1,10 +1,19 @@
 import { type Cleanup, type EffectCallback, type MaybeCleanup, type Signal } from '../graph';
+/** A value that is either synchronous or a `Promise` — used for handler return types in `match()`. */
 type MaybePromise<T> = T | Promise<T>;
+/**
+ * Handlers for all states of one or more signals passed to `match()`.
+ *
+ * @template T - Tuple of `Signal` types being matched
+ */
 type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
+    /** Called when all signals have a value. Receives a tuple of resolved values. */
     ok: (values: {
         [K in keyof T]: T[K] extends Signal<infer V> ? V : never;
     }) => MaybePromise<MaybeCleanup>;
+    /** Called when one or more signals hold an error. Defaults to `console.error`. */
     err?: (errors: readonly Error[]) => MaybePromise<MaybeCleanup>;
+    /** Called when one or more signals are unset (pending). */
     nil?: () => MaybePromise<MaybeCleanup>;
 };
 /**
@@ -38,10 +47,13 @@ type MatchHandlers<T extends readonly Signal<unknown & {}>[]> = {
  */
 declare function createEffect(fn: EffectCallback): Cleanup;
 /**
- * Runs handlers based on the current values of signals.
+ * Reads one or more signals and dispatches to the appropriate handler based on their state.
  * Must be called within an active owner (effect or scope) so async cleanup can be registered.
  *
  * @since 0.15.0
+ * @param signals - Tuple of signals to read; all must have a value for `ok` to run.
+ * @param handlers - Object with an `ok` branch and optional `err` and `nil` branches.
+ * @returns An optional cleanup function if the active handler returns one.
  * @throws RequiredOwnerError If called without an active owner.
  */
 declare function match<T extends readonly Signal<unknown & {}>[]>(signals: readonly [...T], handlers: MatchHandlers<T>): MaybeCleanup;

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

@@ -8,11 +8,31 @@ type DiffResult = {
     change: UnknownRecord;
     remove: UnknownRecord;
 };
+/**
+ * Key generation strategy for `createList` items.
+ * A string value is used as a prefix for auto-incremented keys (`prefix0`, `prefix1`, …).
+ * A function receives each item and returns a stable string key, or `undefined` to fall back to auto-increment.
+ *
+ * @template T - The type of items in the list
+ */
 type KeyConfig<T> = string | ((item: T) => string | undefined);
+/**
+ * Configuration options for `createList`.
+ *
+ * @template T - The type of items in the list
+ */
 type ListOptions<T extends {}> = {
+    /** Key generation strategy. A string prefix or a function `(item) => string | undefined`. Defaults to auto-increment. */
     keyConfig?: KeyConfig<T>;
+    /** Lifecycle callback invoked when the list gains its first downstream subscriber. Must return a cleanup function. */
     watched?: () => Cleanup;
 };
+/**
+ * A reactive ordered array with stable keys and per-item reactivity.
+ * Each item is a `State<T>` signal; structural changes (add/remove/sort) propagate reactively.
+ *
+ * @template T - The type of items in the list
+ */
 type List<T extends {}> = {
     readonly [Symbol.toStringTag]: 'List';
     readonly [Symbol.isConcatSpreadable]: true;
@@ -28,6 +48,13 @@ type List<T extends {}> = {
     indexOfKey(key: string): number;
     add(value: T): string;
     remove(keyOrIndex: string | number): void;
+    /**
+     * Updates an existing item by key, propagating to all subscribers.
+     * No-op if the key does not exist or the value is reference-equal to the current value.
+     * @param key - Stable key of the item to update
+     * @param value - New value for the item
+     */
+    replace(key: string, value: T): void;
     sort(compareFn?: (a: T, b: T) => number): void;
     splice(start: number, deleteCount?: number, ...items: T[]): T[];
     deriveCollection<R extends {}>(callback: (sourceValue: T) => R): Collection<R>;
@@ -51,8 +78,9 @@ declare function getKeyGenerator<T extends {}>(keyConfig?: KeyConfig<T>): [(item
  *
  * @since 0.18.0
  * @param value - Initial array of items
- * @param options - Optional configuration for key generation and watch lifecycle
- * @returns A List signal
+ * @param options.keyConfig - Key generation strategy: string prefix or `(item) => string | undefined`. Defaults to auto-increment.
+ * @param options.watched - Lifecycle callback invoked on first subscriber; must return a cleanup function called on last unsubscribe.
+ * @returns A `List` signal with reactive per-item `State` signals
  */
 declare function createList<T extends {}>(value: T[], options?: ListOptions<T>): List<T>;
 /**

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

@@ -12,7 +12,6 @@ type Memo<T extends {}> = {
      * Recomputes if dependencies have changed since last access.
      * When called inside another reactive context, creates a dependency.
      * @returns The computed value
-     * @throws UnsetSignalValueError If the memo value is still unset when read.
      */
     get(): T;
 };

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

@@ -15,11 +15,9 @@ type Sensor<T extends {}> = {
     get(): T;
 };
 /**
- * A callback function for sensors when the sensor starts being watched.
+ * Configuration options for `createSensor`.
  *
- * @template T - The type of value observed
- * @param set - A function to set the observed value
- * @returns A cleanup function when the sensor stops being watched
+ * @template T - The type of value produced by the sensor
  */
 type SensorOptions<T extends {}> = SignalOptions<T> & {
     /**
@@ -28,6 +26,14 @@ type SensorOptions<T extends {}> = SignalOptions<T> & {
      */
     value?: T;
 };
+/**
+ * Setup callback for `createSensor`. Invoked when the sensor gains its first downstream
+ * subscriber; receives a `set` function to push new values into the graph.
+ *
+ * @template T - The type of value produced by the sensor
+ * @param set - Updates the sensor value and propagates the change to subscribers
+ * @returns A cleanup function invoked when the sensor loses all subscribers
+ */
 type SensorCallback<T extends {}> = (set: (next: T) => void) => Cleanup;
 /**
  * Creates a sensor that tracks external input and updates a state value as long as it is active.

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

@@ -1,7 +1,11 @@
 import { type Cleanup, TYPE_STORE } from '../graph';
 import { type List, type UnknownRecord } from './list';
 import { type State } from './state';
+/**
+ * Configuration options for `createStore`.
+ */
 type StoreOptions = {
+    /** Invoked when the store gains its first downstream subscriber; returns a cleanup called when the last one unsubscribes. */
     watched?: () => Cleanup;
 };
 type BaseStore<T extends UnknownRecord> = {
@@ -19,6 +23,13 @@ type BaseStore<T extends UnknownRecord> = {
     add<K extends keyof T & string>(key: K, value: T[K]): K;
     remove(key: string): void;
 };
+/**
+ * A reactive object with per-property reactivity.
+ * Each property is wrapped as a `State`, nested `Store`, or `List` signal, accessible directly via proxy.
+ * Updating one property only re-runs effects that read that property.
+ *
+ * @template T - The plain-object type whose properties become reactive signals
+ */
 type Store<T extends UnknownRecord> = BaseStore<T> & {
     [K in keyof T]: T[K] extends readonly (infer U extends {})[] ? List<U> : T[K] extends UnknownRecord ? Store<T[K]> : T[K] extends unknown & {} ? State<T[K] & {}> : State<T[K] & {}> | undefined;
 };

package/types/src/signal.d.ts

@@ -4,6 +4,12 @@ import { type Memo } from './nodes/memo';
 import { type State } from './nodes/state';
 import { type Store } from './nodes/store';
 import { type Task } from './nodes/task';
+/**
+ * A readable and writable signal — the type union of `State`, `Store`, and `List`.
+ * Use as a parameter type for generic code that accepts any writable signal.
+ *
+ * @template T - The type of value held by the signal
+ */
 type MutableSignal<T extends {}> = {
     get(): T;
     set(value: T): void;