@zeix/cause-effect 0.18.5 → 1.0.1

package/src/nodes/effect.ts

@@ -20,13 +20,22 @@ import {
 
 /* === Types === */
 
+/** 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>
 }
 
@@ -88,10 +97,13 @@ 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.
  */
 function match<T extends readonly Signal<unknown & {}>[]>(

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
@@ -189,7 +209,8 @@ function diffArrays<T>(
 	const prevByKey = new Map<string, T>()
 	for (let i = 0; i < prev.length; i++) {
 		const key = prevKeys[i]
-		if (key && prev[i]) prevByKey.set(key, prev[i])
+		const item = prev[i]
+		if (key && item !== undefined) prevByKey.set(key, item)
 	}
 
 	// Track which old keys we've seen
@@ -239,8 +260,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[],
@@ -422,7 +444,8 @@ function createList<T extends {}>(
 		},
 
 		at(index: number) {
-			return signals.get(keys[index])
+			const key = keys[index]
+			return key !== undefined ? signals.get(key) : undefined
 		},
 
 		keys() {
@@ -458,6 +481,7 @@ function createList<T extends {}>(
 		remove(keyOrIndex: string | number) {
 			const key =
 				typeof keyOrIndex === 'number' ? keys[keyOrIndex] : keyOrIndex
+			if (key === undefined) return
 			const ok = signals.delete(key)
 			if (ok) {
 				const index =

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/benchmark.test.ts

@@ -298,7 +298,8 @@ for (const framework of [v18]) {
 				Object.fromEntries(heads.map(h => h.read()).entries()),
 			)
 			const splited = heads
-				.map((_, index) => framework.computed(() => mux.read()[index]))
+				// biome-ignore lint/style/noNonNullAssertion: test
+				.map((_, index) => framework.computed(() => mux.read()[index]!))
 				.map(x => framework.computed(() => x.read() + 1))
 
 			for (const x of splited) {
@@ -310,15 +311,19 @@ for (const framework of [v18]) {
 			return () => {
 				for (let i = 0; i < 10; i++) {
 					framework.withBatch(() => {
-						heads[i].write(i)
+						// biome-ignore lint/style/noNonNullAssertion: test
+						heads[i]!.write(i)
 					})
-					expect(splited[i].read()).toBe(i + 1)
+					// biome-ignore lint/style/noNonNullAssertion: test
+					expect(splited[i]!.read()).toBe(i + 1)
 				}
 				for (let i = 0; i < 10; i++) {
 					framework.withBatch(() => {
-						heads[i].write(i * 2)
+						// biome-ignore lint/style/noNonNullAssertion: test
+						heads[i]!.write(i * 2)
 					})
-					expect(splited[i].read()).toBe(i * 2 + 1)
+					// biome-ignore lint/style/noNonNullAssertion: test
+					expect(splited[i]!.read()).toBe(i * 2 + 1)
 				}
 			}
 		})
@@ -455,16 +460,19 @@ for (const framework of [v18]) {
 					})),
 				)
 				const E = framework.computed(() =>
-					hard(C.read() + A.read() + D.read()[0].x, 'E'),
+					// biome-ignore lint/style/noNonNullAssertion: test
+					hard(C.read() + A.read() + D.read()[0]!.x, 'E'),
 				)
 				const F = framework.computed(() =>
-					hard(D.read()[2].x || B.read(), 'F'),
+					// biome-ignore lint/style/noNonNullAssertion: test
+					hard(D.read()[2]!.x || B.read(), 'F'),
 				)
 				const G = framework.computed(
 					() =>
 						C.read() +
 						(C.read() || E.read() % 2) +
-						D.read()[4].x +
+						// biome-ignore lint/style/noNonNullAssertion: test
+						D.read()[4]!.x +
 						F.read(),
 				)
 				framework.effect(() => {
@@ -527,10 +535,16 @@ for (const framework of [v18]) {
 					prop3: framework.signal(3),
 					prop4: framework.signal(4),
 				}
-				let layer: Record<string, Computed<number>> = start
+				type CellxLayer = {
+					prop1: Computed<number>
+					prop2: Computed<number>
+					prop3: Computed<number>
+					prop4: Computed<number>
+				}
+				let layer: CellxLayer = start
 
 				for (let i = layers; i > 0; i--) {
-					const m = layer
+					const m: CellxLayer = layer
 					const s = {
 						prop1: framework.computed(() => m.prop2.read()),
 						prop2: framework.computed(
@@ -598,7 +612,7 @@ for (const framework of [v18]) {
 					end.prop4.read(),
 				]
 
-				return [before, after]
+				return [before, after] as [number[], number[]]
 			}
 
 			for (const layers in expected) {

package/test/collection.test.ts

@@ -498,9 +498,12 @@ describe('Collection', () => {
 
 			const signals = [...doubled]
 			expect(signals).toHaveLength(3)
-			expect(signals[0].get()).toBe(2)
-			expect(signals[1].get()).toBe(4)
-			expect(signals[2].get()).toBe(6)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[0]!.get()).toBe(2)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[1]!.get()).toBe(4)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[2]!.get()).toBe(6)
 		})
 
 		test('should react to source additions', () => {

package/test/effect.test.ts

@@ -414,7 +414,8 @@ describe('match', () => {
 				},
 				err: errors => {
 					errCount++
-					expect(errors[0].message).toBe('Too high')
+					// biome-ignore lint/style/noNonNullAssertion: test
+					expect(errors[0]!.message).toBe('Too high')
 				},
 			}),
 		)

package/test/list.test.ts

@@ -323,7 +323,8 @@ describe('List', () => {
 			const list = createList([10, 20, 30])
 			const allKeys = [...list.keys()]
 			expect(allKeys).toHaveLength(3)
-			expect(list.byKey(allKeys[0])?.get()).toBe(10)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(list.byKey(allKeys[0]!)?.get()).toBe(10)
 		})
 	})
 
@@ -353,9 +354,12 @@ describe('List', () => {
 			const list = createList([10, 20, 30])
 			const signals = [...list]
 			expect(signals).toHaveLength(3)
-			expect(signals[0].get()).toBe(10)
-			expect(signals[1].get()).toBe(20)
-			expect(signals[2].get()).toBe(30)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[0]!.get()).toBe(10)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[1]!.get()).toBe(20)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(signals[2]!.get()).toBe(30)
 		})
 	})
 

package/test/regression.test.ts

@@ -66,7 +66,8 @@ describe('Bundle size', () => {
 			entrypoints: ['./index.ts'],
 			minify: true,
 		})
-		const bytes = await result.outputs[0].arrayBuffer()
+		// biome-ignore lint/style/noNonNullAssertion: test
+		const bytes = await result.outputs[0]!.arrayBuffer()
 		check('bundleMinified', bytes.byteLength, BUNDLE_MARGIN, 'B')
 	})
 
@@ -75,7 +76,8 @@ describe('Bundle size', () => {
 			entrypoints: ['./index.ts'],
 			minify: true,
 		})
-		const bytes = await result.outputs[0].arrayBuffer()
+		// biome-ignore lint/style/noNonNullAssertion: test
+		const bytes = await result.outputs[0]!.arrayBuffer()
 		const gzipped = gzipSync(new Uint8Array(bytes)).byteLength
 		check('bundleGzipped', gzipped, BUNDLE_MARGIN, 'B')
 	})

package/test/store.test.ts

@@ -322,10 +322,14 @@ describe('Store', () => {
 			const user = createStore({ name: 'John', age: 25 })
 			const entries = [...user]
 			expect(entries).toHaveLength(2)
-			expect(entries[0][0]).toBe('name')
-			expect(entries[0][1].get()).toBe('John')
-			expect(entries[1][0]).toBe('age')
-			expect(entries[1][1].get()).toBe(25)
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(entries[0]![0]).toBe('name')
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(entries[0]![1].get()).toBe('John')
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(entries[1]![0]).toBe('age')
+			// biome-ignore lint/style/noNonNullAssertion: test
+			expect(entries[1]![1].get()).toBe(25)
 		})
 
 		test('should maintain property key ordering', () => {

package/test/util/dependency-graph.ts

@@ -53,7 +53,8 @@ export function runGraph(
 ): number {
 	const rand = new Random('seed')
 	const { sources, layers } = graph
-	const leaves = layers[layers.length - 1]
+	// biome-ignore lint/style/noNonNullAssertion: test
+	const leaves = layers[layers.length - 1]!
 	const skipCount = Math.round(leaves.length * (1 - readFraction))
 	const readLeaves = removeElems(leaves, skipCount, rand)
 	const frameworkName = framework.name.toLowerCase()
@@ -65,7 +66,8 @@ export function runGraph(
 		for (let i = 0; i < iterations; i++) {
 			framework.withBatch(() => {
 				const sourceDex = i % sources.length
-				sources[sourceDex].write(i + sourceDex)
+				// biome-ignore lint/style/noNonNullAssertion: test
+				sources[sourceDex]!.write(i + sourceDex)
 			})
 
 			for (const leaf of readLeaves) {
@@ -87,7 +89,8 @@ export function runGraph(
         } */
 
 				const sourceDex = i % sources.length
-				sources[sourceDex].write(i + sourceDex)
+				// biome-ignore lint/style/noNonNullAssertion: test
+				sources[sourceDex]!.write(i + sourceDex)
 
 				for (const leaf of readLeaves) {
 					leaf.read()
@@ -153,7 +156,8 @@ function makeRow(
 	return sources.map((_, myDex) => {
 		const mySources: Computed<number>[] = []
 		for (let sourceDex = 0; sourceDex < nSources; sourceDex++) {
-			mySources.push(sources[(myDex + sourceDex) % sources.length])
+			// biome-ignore lint/style/noNonNullAssertion: test
+			mySources.push(sources[(myDex + sourceDex) % sources.length]!)
 		}
 
 		const staticNode = random.float() < staticFraction
@@ -170,7 +174,8 @@ function makeRow(
 			})
 		} else {
 			// dynamic node, drops one of the sources depending on the value of the first element
-			const first = mySources[0]
+			// biome-ignore lint/style/noNonNullAssertion: test
+			const first = mySources[0]!
 			const tail = mySources.slice(1)
 			const node = framework.computed(() => {
 				counter.count++
@@ -180,7 +185,8 @@ function makeRow(
 
 				for (let i = 0; i < tail.length; i++) {
 					if (shouldDrop && i === dropDex) continue
-					sum += tail[i].read()
+					// biome-ignore lint/style/noNonNullAssertion: test
+					sum += tail[i]!.read()
 				}
 
 				return sum

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,
@@ -19,13 +23,22 @@
 		// Best practices
 		"strict": true,
 		"skipLibCheck": true,
+		"noUncheckedIndexedAccess": true,
+		"exactOptionalPropertyTypes": true,
+		"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"],
+	"exclude": ["node_modules", "types", "index.js"],
 }

package/types/index.d.ts

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

package/types/src/graph.d.ts

@@ -3,11 +3,11 @@ type SourceFields<T extends {}> = {
     value: T;
     sinks: Edge | null;
     sinksTail: Edge | null;
-    stop?: Cleanup;
+    stop?: Cleanup | undefined;
 };
 type OptionsFields<T extends {}> = {
     equals: (a: T, b: T) => boolean;
-    guard?: Guard<T>;
+    guard?: Guard<T> | undefined;
 };
 type SinkFields = {
     fn: unknown;

package/OWNERSHIP_BUG.md

@@ -1,95 +0,0 @@
-# Ownership Bug: Component Scope Disposed by Parent Effect
-
-## Symptom
-
-In `module-todo`, `form-checkbox` elements wired via `checkboxes: pass(...)` lose their
-reactive effects after the initial render — `setProperty('checked')` stops updating
-`input.checked`, and the `on('change')` event listener is silently removed. Reading
-`fc.checked` (a pull) still works correctly, but reactive push is gone.
-
-## Root Cause
-
-`createScope` registers its `dispose` on `prevOwner` — the `activeOwner` at the time the
-scope is created. This is the right behavior for *hierarchical component trees* where a
-parent component logically owns its children. But custom elements have a different ownership
-model: **the DOM owns them**, via `connectedCallback` / `disconnectedCallback`.
-
-The problem arises when a custom element's `connectedCallback` fires *inside* a
-re-runnable reactive effect:
-
-1. `module-todo`'s list sync effect runs inside `flush()` with `activeOwner = listSyncEffect`.
-2. `list.append(li)` connects the `<li>`, which connects the `<form-checkbox>` inside it.
-3. `form-checkbox.connectedCallback()` calls `runEffects(ui, setup(ui))`, which calls
-   `createScope`. `prevOwner = listSyncEffect`, so `dispose` is **registered on
-   `listSyncEffect`**.
-4. Later, the `items = all('li[data-key]')` MutationObserver fires (the DOM mutation from
-   step 2 is detected) and re-queues `listSyncEffect`.
-5. `runEffect(listSyncEffect)` calls `runCleanup(listSyncEffect)`, which calls all
-   registered cleanups — including `form-checkbox`'s `dispose`.
-6. `dispose()` runs `runCleanup(fc1Scope)`, which removes the `on('change')` event
-   listener and trims the `setProperty` effect's reactive subscriptions.
-7. The `<form-checkbox>` elements are still in the DOM, but their effects are permanently
-   gone. `connectedCallback` does not re-fire on already-connected elements.
-
-The same problem recurs whenever `listSyncEffect` re-runs for any reason (e.g. a new todo
-is added), disposing the scopes of all existing `<form-checkbox>` elements.
-
-## Why `unown` Is the Correct Fix
-
-`createScope`'s "register on `prevOwner`" semantics model one ownership relationship:
-*parent reactive scope owns child*. Custom elements model a different one: *the DOM owns
-the component*. `disconnectedCallback` is the authoritative cleanup trigger, not the
-reactive graph.
-
-`unown` is the explicit handshake that says "this scope is DOM-owned". It prevents
-`createScope` from registering `dispose` on whatever reactive effect happens to be running
-when `connectedCallback` fires, while leaving `this.#cleanup` + `disconnectedCallback` as
-the sole lifecycle authority.
-
-A `createScope`-only approach (without `unown`) has two failure modes:
-
-| Scenario | Problem |
-|---|---|
-| Connects in static DOM (`activeOwner = null`) | `dispose` is discarded; effects never cleaned up on disconnect — memory leak |
-| Connects inside a re-runnable effect | Same disposal bug as described above |
-
-Per-item scopes (manually tracking a `Map<key, Cleanup>`) could also fix the disposal
-problem but require significant restructuring of the list sync effect and still need
-`unown` to prevent re-registration on each effect re-run.
-
-## Required Changes
-
-### `@zeix/cause-effect`
-
-**`src/graph.ts`** — Add `unown` next to `untrack`:
-
-```typescript
-/**
- * Runs a callback without any active owner.
- * Any scopes or effects created inside the callback will not be registered as
- * children of the current active owner (e.g. a re-runnable effect). Use this
- * when a component or resource manages its own lifecycle independently of the
- * reactive graph.
- *
- * @since 0.18.5
- */
-function unown<T>(fn: () => T): T {
-    const prev = activeOwner
-    activeOwner = null
-    try {
-        return fn()
-    } finally {
-        activeOwner = prev
-    }
-}
-```
-
-Export it from the internal graph exports and from **`index.ts`**:
-
-```typescript
-export {
-    // ...existing exports...
-    unown,
-    untrack,
-} from './src/graph'
-```